diff options
Diffstat (limited to 'devdocs/html/attributes%2Fpattern.html')
| -rw-r--r-- | devdocs/html/attributes%2Fpattern.html | 143 |
1 files changed, 143 insertions, 0 deletions
diff --git a/devdocs/html/attributes%2Fpattern.html b/devdocs/html/attributes%2Fpattern.html new file mode 100644 index 00000000..126d4f69 --- /dev/null +++ b/devdocs/html/attributes%2Fpattern.html @@ -0,0 +1,143 @@ +<header><h1>HTML attribute: pattern</h1></header><div class="section-content"><p>The <code>pattern</code> attribute specifies a <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions">regular expression</a> the form control's value should match. If a non-<code>null</code> value doesn't conform to the constraints set by the <code>pattern</code> value, the <a href="https://developer.mozilla.org/en-US/docs/Web/API/ValidityState"><code>ValidityState</code></a> object's read-only <a href="https://developer.mozilla.org/en-US/docs/Web/API/ValidityState/patternMismatch"><code>patternMismatch</code></a> property will be true.</p></div> +<h2 id="try_it">Try it</h2> +<div class="section-content"><iframe class="interactive is-tabbed-shorter-height" height="200" src="https://interactive-examples.mdn.mozilla.net/pages/tabbed/attribute-pattern.html" title="MDN Web Docs Interactive Example" loading="lazy"></iframe></div> +<h2 id="overview">Overview</h2> +<div class="section-content"> +<p>The <code>pattern</code> attribute is an attribute of the <a href="../element/input/text">text</a>, <a href="../element/input/tel">tel</a>, <a href="../element/input/email">email</a>, <a href="../element/input/url">url</a>, <a href="../element/input/password">password</a>, and <a href="../element/input/search">search</a> input types.</p> <p>The <code>pattern</code> attribute, when specified, is a regular expression which the input's <a href="../element/input#value"><code>value</code></a> must match for the value to pass <a href="../constraint_validation">constraint validation</a>. It must be a valid JavaScript regular expression, as used by the <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp"><code>RegExp</code></a> type, and as documented in our <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions">guide on regular expressions</a>; the <code>'u'</code> flag is specified when compiling the regular expression so that the pattern is treated as a sequence of Unicode code points, instead of as ASCII. No forward slashes should be specified around the pattern text.</p> <p>If the specified pattern is not specified or is invalid, no regular expression is applied and this attribute is ignored.</p> <div class="notecard note" id="sect1"> <p><strong>Note:</strong> Use the <a href="../element/input#title"><code>title</code></a> attribute to specify text that most browsers will display as a tooltip to explain what the requirements are to match the pattern. You <strong>must not</strong> rely on the tooltip alone for an explanation. See below for more information on usability.</p> </div> <p>Some of the input types supporting the pattern attribute, notably the <a href="../element/input/email">email</a> and <a href="../element/input/url">url</a> input types, have expected value syntaxes that must be matched. If the pattern attribute isn't present, and the value doesn't match the expected syntax for that value type, the <a href="https://developer.mozilla.org/en-US/docs/Web/API/ValidityState"><code>ValidityState</code></a> object's read-only <a href="https://developer.mozilla.org/en-US/docs/Web/API/ValidityState/typeMismatch"><code>typeMismatch</code></a> property will be true.</p> +</div> +<h3 id="usability">Usability</h3> +<div class="section-content"><p>When including a <code>pattern</code>, provide a description of the pattern in visible text near the control. Additionally, include a <a href="../global_attributes/title"><code>title</code></a> attribute which gives a description of the pattern. User agents may use the title contents during constraint validation to tell the user that the pattern is not matched. Some browsers show a tooltip with title contents, improving usability for sighted users. Additionally, assistive technology may read the title aloud when the control gains focus, but this should not be relied upon for accessibility.</p></div> +<h3 id="constraint_validation">Constraint validation</h3> +<div class="section-content"> +<p> If the input's value is not the empty string and the value does not match the entire regular expression, there is a constraint violation reported by the <a href="https://developer.mozilla.org/en-US/docs/Web/API/ValidityState"><code>ValidityState</code></a> object's <a href="https://developer.mozilla.org/en-US/docs/Web/API/ValidityState/patternMismatch"><code>patternMismatch</code></a> property being <code>true</code>. The pattern's regular expression, when matched against the value, must have its start anchored to the start of the string and its end anchored to the end of the string, which is slightly different from JavaScript regular expressions: in the case of pattern attribute, we are matching against the entire value, not just any subset, as if a <code>^(?:</code> were implied at the start of the pattern and <code>)$</code> at the end. </p> <div class="notecard note" id="sect2"> <p><strong>Note:</strong> If the <code>pattern</code> attribute is specified with no value, its value is implicitly the empty string. Thus, <strong>any non-empty</strong> input <code>value</code> will result in constraint violation.</p> </div> +</div> +<h2 id="examples">Examples</h2> + +<h3 id="matching_a_phone_number">Matching a phone number</h3> +<div class="section-content"> +<p>Given the following:</p> <div class="code-example"> +<p class="example-header"><span class="language-name">html</span></p> +<pre data-signature="bSNhJiPOVFDeFrcbD2TBpPUo4vQe8EA1m95U94Ywec8=" data-language="html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>label</span><span class="token punctuation">></span></span> + Enter your phone number in the format (123) - 456 - 7890 (<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>input</span> + <span class="token attr-name">name</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>tel1<span class="token punctuation">"</span></span> + <span class="token attr-name">type</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>tel<span class="token punctuation">"</span></span> + <span class="token attr-name">pattern</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>[0-9]{3}<span class="token punctuation">"</span></span> + <span class="token attr-name">placeholder</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>###<span class="token punctuation">"</span></span> + <span class="token attr-name">aria-label</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>3-digit area code<span class="token punctuation">"</span></span> + <span class="token attr-name">size</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>2<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span>) - + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>input</span> + <span class="token attr-name">name</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>tel2<span class="token punctuation">"</span></span> + <span class="token attr-name">type</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>tel<span class="token punctuation">"</span></span> + <span class="token attr-name">pattern</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>[0-9]{3}<span class="token punctuation">"</span></span> + <span class="token attr-name">placeholder</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>###<span class="token punctuation">"</span></span> + <span class="token attr-name">aria-label</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>3-digit prefix<span class="token punctuation">"</span></span> + <span class="token attr-name">size</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>2<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span> + - + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>input</span> + <span class="token attr-name">name</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>tel3<span class="token punctuation">"</span></span> + <span class="token attr-name">type</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>tel<span class="token punctuation">"</span></span> + <span class="token attr-name">pattern</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>[0-9]{4}<span class="token punctuation">"</span></span> + <span class="token attr-name">placeholder</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>####<span class="token punctuation">"</span></span> + <span class="token attr-name">aria-label</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>4-digit number<span class="token punctuation">"</span></span> + <span class="token attr-name">size</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>3<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"></</span>label</span><span class="token punctuation">></span></span> +<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>p</span><span class="token punctuation">></span></span> +</pre> +</div> <p>Here we have 3 sections for a north American phone number with an implicit label encompassing all three components of the phone number, expecting 3-digits, 3-digits and 4-digits respectively, as defined by the <code>pattern</code> attribute set on each.</p> <p>If the values are too long or too short, or contain characters that aren't digits, the <code>patternMismatch</code> will be true. When <code>true</code>, the element matches the <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/:invalid"><code>:invalid</code></a> CSS pseudo-classes.</p> <div class="code-example"> +<p class="example-header"><span class="language-name">css</span></p> +<pre data-signature="wBpzHvL3Pu7mzdO6qRM7EYa0KIfeehgEAeIrvwIRltw=" data-language="css"><span class="token selector">input:invalid</span> <span class="token punctuation">{</span> + <span class="token property">border</span><span class="token punctuation">:</span> red solid 3px<span class="token punctuation">;</span> +<span class="token punctuation">}</span> +</pre> +</div> +<div class="code-example" id="sect3"> + +<iframe class="sample-code-frame" title="Matching a phone number sample" id="frame_matching_a_phone_number" width="300" height="80" src="https://live.mdnplay.dev/en-US/docs/Web/HTML/Attributes/pattern/runner.html?id=matching_a_phone_number" loading="lazy"></iframe> +</div> <p>If we had used <a href="minlength"><code>minlength</code></a> and <a href="maxlength"><code>maxlength</code></a> attributes instead, we may have seen <a href="https://developer.mozilla.org/en-US/docs/Web/API/ValidityState/tooLong"><code>validityState.tooLong</code></a> or <a href="https://developer.mozilla.org/en-US/docs/Web/API/ValidityState/tooShort"><code>validityState.tooShort</code></a> being true.</p> +</div> +<h3 id="specifying_a_pattern">Specifying a pattern</h3> +<div class="section-content"> +<p>You can use the <a href="../element/input#pattern"><code>pattern</code></a> attribute to specify a regular expression that the inputted value must match in order to be considered valid (see <a href="https://developer.mozilla.org/en-US/docs/Learn/Forms/Form_validation#validating_against_a_regular_expression">Validating against a regular expression</a> for a simple crash course on using regular expressions to validate inputs).</p> <p>The example below restricts the value to 4-8 characters and requires that it contain only lower-case letters.</p> <div class="code-example"> +<p class="example-header"><span class="language-name">html</span></p> +<pre data-signature="efeBlE0yUh+25rwG8YBXEKbzp6i7eZOW/uyDSEIiG2Y=" data-language="html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>form</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>label</span> <span class="token attr-name">for</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>uname<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Choose a username: <span class="token tag"><span class="token tag"><span class="token punctuation"></</span>label</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>input</span> + <span class="token attr-name">type</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>text<span class="token punctuation">"</span></span> + <span class="token attr-name">id</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>uname<span class="token punctuation">"</span></span> + <span class="token attr-name">name</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>name<span class="token punctuation">"</span></span> + <span class="token attr-name">required</span> + <span class="token attr-name">size</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>45<span class="token punctuation">"</span></span> + <span class="token attr-name">pattern</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>[a-z]{4,8}<span class="token punctuation">"</span></span> + <span class="token attr-name">title</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>4 to 8 lowercase letters<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>span</span> <span class="token attr-name">class</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>validity<span class="token punctuation">"</span></span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"></</span>span</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>Usernames must be lowercase and 4-8 characters in length.<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>p</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>button</span><span class="token punctuation">></span></span>Submit<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>button</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span> +<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>form</span><span class="token punctuation">></span></span> +</pre> +</div> <p>This renders like so:</p> +<div class="code-example" id="sect4"> + +<iframe class="sample-code-frame" title="Specifying a pattern sample" id="frame_specifying_a_pattern" width="600" height="110" src="https://live.mdnplay.dev/en-US/docs/Web/HTML/Attributes/pattern/runner.html?id=specifying_a_pattern" loading="lazy"></iframe> +</div> +</div> +<h3 id="accessibility_concerns">Accessibility Concerns</h3> +<div class="section-content"> +<p>When a control has a <code>pattern</code> attribute, the <code>title</code> attribute, if used, must describe the pattern. Relying on the <code>title</code> attribute for the visual display of text content is generally discouraged as many user agents do not expose the attribute in an accessible manner. Some browsers show a tooltip when an element with a title is hovered, but that leaves out keyboard-only and touch-only users. This is one of the several reasons you must include information informing users how to fill out the control to match the requirements.</p> <p>While <code>title</code>s are used by some browsers to populate error messaging, because browsers sometimes also show the title as text on hover, it therefore shows in non-error situations, so be careful not to word titles as if an error has occurred.</p> +</div> +<h2 id="specifications">Specifications</h2> +<div class="_table"><table class="standard-table"> +<thead><tr><th scope="col">Specification</th></tr></thead> +<tbody><tr><td><a href="https://html.spec.whatwg.org/multipage/input.html#attr-input-pattern">HTML Standard <br><small># attr-input-pattern</small></a></td></tr></tbody> +</table></div> +<h2 id="browser_compatibility">Browser compatibility</h2> +<div class="_table"><table> +<thead> +<tr id="bct-browser-type"> +<th></th> +<th colspan="6">Desktop</th> +<th colspan="6">Mobile</th> +</tr> +<tr id="bct-browsers"> +<th></th> +<th>Chrome</th> +<th>Edge</th> +<th>Firefox</th> +<th>Internet Explorer</th> +<th>Opera</th> +<th>Safari</th> +<th>WebView Android</th> +<th>Chrome Android</th> +<th>Firefox for Android</th> +<th>Opera Android</th> +<th>Safari on IOS</th> +<th>Samsung Internet</th> +</tr> +</thead> +<tbody><tr> +<th><code>pattern</code></th> +<td class="bc-supports-yes">4</td> +<td class="bc-supports-yes">12</td> +<td class="bc-supports-yes">4</td> +<td class="bc-supports-yes">10</td> +<td class="bc-supports-yes">≤12.1</td> +<td class="bc-supports-yes">5</td> +<td class="bc-supports-yes">≤37</td> +<td class="bc-supports-yes">18</td> +<td class="bc-supports-yes">4</td> +<td class="bc-supports-yes">≤12.1</td> +<td class="bc-supports-yes">4</td> +<td class="bc-supports-yes">1.0</td> +</tr></tbody> +</table></div> +<h2 id="see_also">See also</h2> +<div class="section-content"><ul> <li><a href="../constraint_validation">Constraint validation</a></li> <li><a href="https://developer.mozilla.org/en-US/docs/Learn/Forms/Form_validation">Forms: Data form validation</a></li> <li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions">Regular Expressions</a></li> </ul></div><div class="_attribution"> + <p class="_attribution-p"> + © 2005–2023 MDN contributors.<br>Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.<br> + <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern" class="_attribution-link">https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern</a> + </p> +</div> |