diff options
| author | Craig Jennings <c@cjennings.net> | 2024-04-07 13:41:34 -0500 |
|---|---|---|
| committer | Craig Jennings <c@cjennings.net> | 2024-04-07 13:41:34 -0500 |
| commit | 754bbf7a25a8dda49b5d08ef0d0443bbf5af0e36 (patch) | |
| tree | f1190704f78f04a2b0b4c977d20fe96a828377f1 /devdocs/html/element%2Flabel.html | |
new repository
Diffstat (limited to 'devdocs/html/element%2Flabel.html')
| -rw-r--r-- | devdocs/html/element%2Flabel.html | 163 |
1 files changed, 163 insertions, 0 deletions
diff --git a/devdocs/html/element%2Flabel.html b/devdocs/html/element%2Flabel.html new file mode 100644 index 00000000..bd85c5ef --- /dev/null +++ b/devdocs/html/element%2Flabel.html @@ -0,0 +1,163 @@ +<header><h1><label>: The Label element</h1></header><div class="section-content"><p>The <code><label></code> <a href="../index">HTML</a> element represents a caption for an item in a user interface.</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/label.html" title="MDN Web Docs Interactive Example" loading="lazy"></iframe> <p>Associating a <code><label></code> with a form control, such as <a href="input"><code><input></code></a> or <a href="textarea"><code><textarea></code></a> offers some major advantages:</p> <ul> <li>The label text is not only visually associated with its corresponding text input; it is programmatically associated with it too. This means that, for example, a screen reader will read out the label when the user is focused on the form input, making it easier for an assistive technology user to understand what data should be entered.</li> <li>When a user clicks or touches/taps a label, the browser passes the focus to its associated input (the resulting event is also raised for the input). That increased hit area for focusing the input provides an advantage to anyone trying to activate it — including those using a touch-screen device.</li> </ul> <p>To explicitly associate a <code><label></code> element with an <code><input></code> element, you first need to add the <code>id</code> attribute to the <code><input></code> element. Next, you add the <code>for</code> attribute to the <code><label></code> element, where the value of <code>for</code> is the same as the <code>id</code> in the <code><input></code> element.</p> <p>Alternatively, you can nest the <code><input></code> directly inside the <code><label></code>, in which case the <code>for</code> and <code>id</code> attributes are not needed because the association is implicit:</p> <div class="code-example"> +<p class="example-header"><span class="language-name">html</span></p> +<pre data-signature="AhbN4XMmwVUdlXr/epl2ZoZtkoH6Z/oLycoxC/M9Cdk=" data-language="html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>label</span><span class="token punctuation">></span></span> + Do you like peas? + <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>checkbox<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>peas<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> +</pre> +</div> <p>The form control that a label is labeling is called the <em>labeled control</em> of the label element. Multiple labels can be associated with the same form control:</p> <div class="code-example"> +<p class="example-header"><span class="language-name">html</span></p> +<pre data-signature="p/y8SAuSdhvsGlGe0d09441fqspimX5+IxypUUshDSs=" data-language="html"><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>username<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Enter your 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">id</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>username<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>username<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>text<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 attr-name">for</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>username<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Forgot your username?<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>label</span><span class="token punctuation">></span></span> +</pre> +</div> <p>Elements that can be associated with a <code><label></code> element include <a href="button"><code><button></code></a>, <a href="input"><code><input></code></a> (except for <code>type="hidden"</code>), <a href="meter"><code><meter></code></a>, <a href="output"><code><output></code></a>, <a href="progress"><code><progress></code></a>, <a href="select"><code><select></code></a> and <a href="textarea"><code><textarea></code></a>.</p> +</div> +<h2 id="attributes">Attributes</h2> +<div class="section-content"> +<p>This element includes the <a href="../global_attributes">global attributes</a>.</p> <dl> <dt id="for"><a href="#for"><code>for</code></a></dt> <dd> <p>The value of the <code>for</code> attribute must be a single <a href="../global_attributes#id"><code>id</code></a> for a <a href="../content_categories#labelable">labelable</a> form-related element in the same document as the <code><label></code> element. So, any given <code>label</code> element can be associated with only one form control.</p> <div class="notecard note" id="sect1"> <p><strong>Note:</strong> To programmatically set the <code>for</code> attribute, use <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/htmlFor"><code>htmlFor</code></a>.</p> </div> <p>The first element in the document with an <code>id</code> attribute matching the value of the <code>for</code> attribute is the <em>labeled control</em> for this <code>label</code> element — if the element with that <code>id</code> is actually a <a href="https://html.spec.whatwg.org/multipage/forms.html#category-label" target="_blank">labelable element</a>. If it is <em>not</em> a labelable element, then the <code>for</code> attribute has no effect. If there are other elements that also match the <code>id</code> value, later in the document, they are not considered.</p> <p>Multiple <code>label</code> elements can be given the same value for their <code>for</code> attribute; doing so causes the associated form control (the form control that <code>for</code> value references) to have multiple labels.</p> <div class="notecard note" id="sect2"> <p><strong>Note:</strong> A <code><label></code> element can have both a <code>for</code> attribute and a contained control element, as long as the <code>for</code> attribute points to the contained control element.</p> </div> </dd> </dl> +</div> +<h2 id="styling_with_css">Styling with CSS</h2> +<div class="section-content"><p>There are no special styling considerations for <code><label></code> elements — structurally they are simple inline elements, and so can be styled in much the same way as a <a href="span"><code><span></code></a> or <a href="a"><code><a></code></a> element. You can apply styling to them in any way you want, as long as you don't cause the text to become difficult to read.</p></div> +<h2 id="examples">Examples</h2> + +<h3 id="defining_an_implicit_label">Defining an implicit label</h3> +<div class="section-content"> +<div class="code-example"> +<p class="example-header"><span class="language-name">html</span></p> +<pre data-signature="zW3MmaUYroG77TWJSIxrKzZE4RkU5OJPPqJ/KgNIGD0=" data-language="html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>label</span><span class="token punctuation">></span></span>Click me <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 punctuation">/></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"></</span>label</span><span class="token punctuation">></span></span> +</pre> +</div> +<div class="code-example" id="sect3"> + +<iframe class="sample-code-frame" title="Defining an implicit label" id="frame_simple_label_example" width="200" height="60" src="https://live.mdnplay.dev/en-US/docs/Web/HTML/Element/label/runner.html?id=simple_label_example" loading="lazy"></iframe> +</div> +</div> +<h3 id="defining_an_explicit_label_with_the_for_attribute">Defining an explicit label with the "for" attribute</h3> +<div class="section-content"> +<div class="code-example"> +<p class="example-header"><span class="language-name">html</span></p> +<pre data-signature="FJoTP/pDVUzrBSJlEQZHU1RkCfAqfIAuPO9IejzEm24=" data-language="html"><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>username<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Click me to focus on the input field<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>username<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span> +</pre> +</div> +<div class="code-example" id="sect4"> + +<iframe class="sample-code-frame" title='Defining an explicit label with the "for" attribute' id="frame_using_the_for_attribute" width="200" height="60" src="https://live.mdnplay.dev/en-US/docs/Web/HTML/Element/label/runner.html?id=using_the_for_attribute" loading="lazy"></iframe> +</div> +</div> +<h2 id="accessibility_concerns">Accessibility concerns</h2> + +<h3 id="interactive_content">Interactive content</h3> +<div class="section-content"> +<p>Don't place interactive elements such as <a href="a">anchors</a> or <a href="button">buttons</a> inside a <code>label</code>. Doing so makes it difficult for people to activate the form input associated with the <code>label</code>.</p> <p><strong>Don't do this:</strong></p> <div class="code-example"> +<p class="example-header"><span class="language-name">html</span></p> +<pre data-signature="epJVCPTN1DLAdZwplkXthSuVyiJoerAoyIqtRGfE8LA=" data-language="html"><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>tac<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">id</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>tac<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>checkbox<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>terms-and-conditions<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span> + I agree to the <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>a</span> <span class="token attr-name">href</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>terms-and-conditions.html<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Terms and Conditions<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>a</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> +</pre> +</div> <p><strong>Prefer this:</strong></p> <div class="code-example"> +<p class="example-header"><span class="language-name">html</span></p> +<pre data-signature="gFBBDE3RMFHvSVSD+vt0qoHK+7QzrnZZXmtlFJ0wT6Q=" data-language="html"><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>tac<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">id</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>tac<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>checkbox<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>terms-and-conditions<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span> + I agree to the Terms and Conditions +<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> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>a</span> <span class="token attr-name">href</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>terms-and-conditions.html<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Read our Terms and Conditions<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>a</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> +</div> +<h3 id="headings">Headings</h3> +<div class="section-content"> +<p>Placing <a href="heading_elements">heading elements</a> within a <code><label></code> interferes with many kinds of assistive technology, because headings are commonly used as <a href="heading_elements#navigation">a navigation aid</a>. If the label's text needs to be adjusted visually, use CSS classes applied to the <code><label></code> element instead.</p> <p>If a <a href="form">form</a>, or a section of a form needs a title, use the <a href="legend"><code><legend></code></a> element placed within a <a href="fieldset"><code><fieldset></code></a>.</p> <p><strong>Don't do this:</strong></p> <div class="code-example"> +<p class="example-header"><span class="language-name">html</span></p> +<pre data-signature="Nncfx6JqBjmvXGwg6eqjkitN3xmJQx91CUrovtNpnoc=" data-language="html"><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>your-name<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>h3</span><span class="token punctuation">></span></span>Your name<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>h3</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">id</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>your-name<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>your-name<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>text<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> +</pre> +</div> <p><strong>Prefer this:</strong></p> <div class="code-example"> +<p class="example-header"><span class="language-name">html</span></p> +<pre data-signature="FXaFdhbRkL6arJ2NGvxQFIb+GBqLOh7pk37rLHUiiCI=" data-language="html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>label</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>large-label<span class="token punctuation">"</span></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>your-name<span class="token punctuation">"</span></span><span class="token punctuation">></span></span> + Your name + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>input</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>your-name<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>your-name<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>text<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> +</pre> +</div> +</div> +<h3 id="buttons">Buttons</h3> +<div class="section-content"><p>An <a href="input"><code><input></code></a> element with a <code>type="button"</code> declaration and a valid <code>value</code> attribute does not need a label associated with it. Doing so may actually interfere with how assistive technology parses the button input. The same applies for the <a href="button"><code><button></code></a> element.</p></div> +<h2 id="technical_summary">Technical summary</h2> +<div class="section-content"><figure class="table-container"><div class="_table"><table class="properties"> <tbody> <tr> <th scope="row"><a href="../content_categories">Content categories</a></th> <td> <a href="../content_categories#flow_content">Flow content</a>, <a href="../content_categories#phrasing_content">phrasing content</a>, <a href="../content_categories#interactive_content">interactive content</a>, <a href="../content_categories#form-associated_content">form-associated element</a>, palpable content. </td> </tr> <tr> <th scope="row">Permitted content</th> <td> <a href="../content_categories#phrasing_content">Phrasing content</a>, but no descendant <code>label</code> elements. No <a href="../content_categories#labelable">labelable</a> elements other than the labeled control are allowed. </td> </tr> <tr> <th scope="row">Tag omission</th> <td>None, both the starting and ending tag are mandatory.</td> </tr> <tr> <th scope="row">Permitted parents</th> <td> Any element that accepts <a href="../content_categories#phrasing_content">phrasing content</a>. </td> </tr> <tr> <th scope="row">Implicit ARIA role</th> <td><a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role" target="_blank">No corresponding role</a></td> </tr> <tr> <th scope="row">Permitted ARIA roles</th> <td>No <code>role</code> permitted</td> </tr> <tr> <th scope="row">DOM interface</th> <td><a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement"><code>HTMLLabelElement</code></a></td> </tr> </tbody> </table></div></figure></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/forms.html#the-label-element">HTML Standard <br><small># the-label-element</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>label</code></th> +<td class="bc-supports-yes">1</td> +<td class="bc-supports-yes">12</td> +<td class="bc-supports-yes">1</td> +<td class="bc-supports-yes">Yes</td> +<td class="bc-supports-yes">15</td> +<td class="bc-supports-yes">≤4</td> +<td class="bc-supports-yes">4.4</td> +<td class="bc-supports-yes">18</td> +<td class="bc-supports-yes">4</td> +<td class="bc-supports-yes">14</td> +<td class="bc-supports-yes">≤3.2</td> +<td class="bc-supports-yes">1.0</td> +</tr> +<tr> +<th><code>for</code></th> +<td class="bc-supports-yes">1</td> +<td class="bc-supports-yes">12</td> +<td class="bc-supports-yes">1</td> +<td class="bc-supports-yes">Yes</td> +<td class="bc-supports-yes">15</td> +<td class="bc-supports-yes">≤4</td> +<td class="bc-supports-yes">4.4</td> +<td class="bc-supports-yes">18</td> +<td class="bc-supports-yes">4</td> +<td class="bc-supports-yes">14</td> +<td class="bc-supports-yes">≤3.2</td> +<td class="bc-supports-yes">1.0</td> +</tr> +</tbody> +</table></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/Element/label" class="_attribution-link">https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label</a> + </p> +</div> |