diff options
Diffstat (limited to 'devdocs/html/element%2Finput%2Fcheckbox.html')
| -rw-r--r-- | devdocs/html/element%2Finput%2Fcheckbox.html | 288 |
1 files changed, 288 insertions, 0 deletions
diff --git a/devdocs/html/element%2Finput%2Fcheckbox.html b/devdocs/html/element%2Finput%2Fcheckbox.html new file mode 100644 index 00000000..39e3a39d --- /dev/null +++ b/devdocs/html/element%2Finput%2Fcheckbox.html @@ -0,0 +1,288 @@ +<header><h1><input type="checkbox"></h1></header><div class="section-content"><p><a href="../input"><code><input></code></a> elements of type <code>checkbox</code> are rendered by default as boxes that are checked (ticked) when activated, like you might see in an official government paper form. The exact appearance depends upon the operating system configuration under which the browser is running. Generally this is a square but it may have rounded corners. A checkbox allows you to select single values for submission in a form (or not).</p></div> +<h2 id="try_it">Try it</h2> +<div class="section-content"> +<iframe class="interactive is-tabbed-standard-height" height="200" src="https://interactive-examples.mdn.mozilla.net/pages/tabbed/input-checkbox.html" title="MDN Web Docs Interactive Example" loading="lazy"></iframe> <div class="notecard note" id="sect1"> <p><strong>Note:</strong> <a href="radio">Radio buttons</a> are similar to checkboxes, but with an important distinction — <a href="radio#defining_a_radio_group">same-named radio buttons</a> are grouped into a set in which only one radio button can be selected at a time, whereas checkboxes allow you to turn single values on and off. Where multiple same-named controls exist, radio buttons allow one to be selected out of them all, whereas checkboxes allow multiple values to be selected.</p> </div> +</div> +<h2 id="value">Value</h2> +<div class="section-content"> +<p>A string representing the value of the checkbox. This is not displayed on the client-side, but on the server this is the <code>value</code> given to the data submitted with the checkbox's <code>name</code>. Take the following example:</p> <div class="code-example"> +<p class="example-header"><span class="language-name">html</span></p> +<pre data-signature="hxMKBon9N3J8fyT7DXYx+9AN8BwuHXRDYGXS38TWjYM=" 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>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">id</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>subscribeNews<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>subscribe<span class="token punctuation">"</span></span> + <span class="token attr-name">value</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>newsletter<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>subscribeNews<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Subscribe to newsletter?<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>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 attr-name">type</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>submit<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Subscribe<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>In this example, we've got a name of <code>subscribe</code>, and a value of <code>newsletter</code>. When the form is submitted, the data name/value pair will be <code>subscribe=newsletter</code>.</p> <p>If the <code>value</code> attribute was omitted, the default value for the checkbox is <code>on</code>, so the submitted data in that case would be <code>subscribe=on</code>.</p> <div class="notecard note" id="sect2"> <p><strong>Note:</strong> If a checkbox is unchecked when its form is submitted, neither the name nor the value is submitted to the server. There is no HTML-only method of representing a checkbox's unchecked state (e.g. <code>value=unchecked</code>). If you wanted to submit a default value for the checkbox when it is unchecked, you could include JavaScript to create a <a href="hidden"><input type="hidden"></a> within the form with a value indicating an unchecked state.</p> </div> +</div> +<h2 id="additional_attributes">Additional attributes</h2> +<div class="section-content"> +<p>In addition to the common attributes shared by all <a href="../input"><code><input></code></a> elements, "<code>checkbox</code>" inputs support the following attributes.</p> <dl> <dt id="checked"><a href="#checked"><code>checked</code></a></dt> <dd> <p>A <a href="https://developer.mozilla.org/en-US/docs/Glossary/Boolean/HTML">boolean</a> attribute indicating whether this checkbox is checked by default (when the page loads). It does <em>not</em> indicate whether this checkbox is currently checked: if the checkbox's state is changed, this content attribute does not reflect the change. (Only the <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement"><code>HTMLInputElement</code></a>'s <code>checked</code> IDL attribute is updated.)</p> <div class="notecard note" id="sect3"> <p> <strong>Note:</strong> Unlike other input controls, a checkbox's value is only included in the submitted data if the checkbox is currently <code>checked</code>. If it is, then the value of the checkbox's <code>value</code> attribute is reported as the input's value, or <code>on</code> if no <code>value</code> is set. Unlike other browsers, Firefox by default <a href="https://stackoverflow.com/questions/5985839/bug-with-firefox-disabled-attribute-of-input-not-resetting-when-refreshing" target="_blank">persists the dynamic checked state</a> of an <code><input></code> across page loads. Use the <a href="../input#autocomplete"><code>autocomplete</code></a> attribute to control this feature. </p> </div> </dd> <dt id="value_2"><a href="#value_2"><code>value</code></a></dt> <dd> <p>The <code>value</code> attribute is one which all <a href="../input"><code><input></code></a>s share; however, it serves a special purpose for inputs of type <code>checkbox</code>: when a form is submitted, only checkboxes which are currently checked are submitted to the server, and the reported value is the value of the <code>value</code> attribute. If the <code>value</code> is not otherwise specified, it is the string <code>on</code> by default. This is demonstrated in the section <a href="#value">Value</a> above.</p> </dd> </dl> +</div> +<h2 id="using_checkbox_inputs">Using checkbox inputs</h2> +<div class="section-content"><p>We already covered the most basic use of checkboxes above. Let's now look at the other common checkbox-related features and techniques you'll need.</p></div> +<h3 id="handling_multiple_checkboxes">Handling multiple checkboxes</h3> +<div class="section-content"> +<p>The example we saw above only contained one checkbox; in real-world situations you'll be likely to encounter multiple checkboxes. If they are completely unrelated, then you can just deal with them all separately, as shown above. However, if they're all related, things are not quite so simple.</p> <p>For example, in the following demo we include multiple checkboxes to allow the user to select their interests (see the full version in the <a href="#examples">Examples</a> section).</p> <div class="code-example"> +<p class="example-header"><span class="language-name">html</span></p> +<pre data-signature="RYlgJxaHJeQATWTIXB9kcLniH2At+uy5Sf4Po5b91Hg=" data-language="html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>fieldset</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>legend</span><span class="token punctuation">></span></span>Choose your interests<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>legend</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>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">id</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>coding<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>interest<span class="token punctuation">"</span></span> <span class="token attr-name">value</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>coding<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>coding<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Coding<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>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>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">id</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>music<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>interest<span class="token punctuation">"</span></span> <span class="token attr-name">value</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>music<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>music<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Music<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>div</span><span class="token punctuation">></span></span> +<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>fieldset</span><span class="token punctuation">></span></span> +</pre> +</div> +<div class="code-example" id="sect4"> + +<iframe class="sample-code-frame" title="Handling multiple checkboxes sample" id="frame_handling_multiple_checkboxes" width="600" height="100" src="https://live.mdnplay.dev/en-US/docs/Web/HTML/Element/input/checkbox/runner.html?id=handling_multiple_checkboxes" loading="lazy"></iframe> +</div> <p>In this example you will see that we've given each checkbox the same <code>name</code>. If both checkboxes are checked and then the form is submitted, you'll get a string of name/value pairs submitted like this: <code>interest=coding&interest=music</code>. When this string reaches the server, you need to parse it other than as an associative array, so all values, not only the last value, of <code>interest</code> are captured. For one technique used with Python, see <a href="https://stackoverflow.com/questions/18745456/handle-multiple-checkboxes-with-a-single-serverside-variable" target="_blank">Handle Multiple Checkboxes with a Single Serverside Variable</a>, for example.</p> +</div> +<h3 id="checking_boxes_by_default">Checking boxes by default</h3> +<div class="section-content"> +<p>To make a checkbox checked by default, you give it the <code>checked</code> attribute. See the below example:</p> <div class="code-example"> +<p class="example-header"><span class="language-name">html</span></p> +<pre data-signature="tx0xR+ubD2wkXkKziZyEazEMFsFjOMvYciqtaeNZU6Q=" data-language="html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>fieldset</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>legend</span><span class="token punctuation">></span></span>Choose your interests<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>legend</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>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">id</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>coding<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>interest<span class="token punctuation">"</span></span> <span class="token attr-name">value</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>coding<span class="token punctuation">"</span></span> <span class="token attr-name">checked</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>coding<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Coding<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>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>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">id</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>music<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>interest<span class="token punctuation">"</span></span> <span class="token attr-name">value</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>music<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>music<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Music<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>div</span><span class="token punctuation">></span></span> +<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>fieldset</span><span class="token punctuation">></span></span> +</pre> +</div> +<div class="code-example" id="sect5"> + +<iframe class="sample-code-frame" title="Checking boxes by default sample" id="frame_checking_boxes_by_default" width="600" height="100" src="https://live.mdnplay.dev/en-US/docs/Web/HTML/Element/input/checkbox/runner.html?id=checking_boxes_by_default" loading="lazy"></iframe> +</div> +</div> +<h3 id="providing_a_bigger_hit_area_for_your_checkboxes">Providing a bigger hit area for your checkboxes</h3> +<div class="section-content"> +<p>In the above examples, you may have noticed that you can toggle a checkbox by clicking on its associated <a href="../label"><code><label></code></a> element as well as on the checkbox itself. This is a really useful feature of HTML form labels that makes it easier to click the option you want, especially on small-screen devices like smartphones.</p> <p>Beyond accessibility, this is another good reason to properly set up <code><label></code> elements on your forms.</p> +</div> +<h3 id="indeterminate_state_checkboxes">Indeterminate state checkboxes</h3> +<div class="section-content"> +<p>In addition to the checked and unchecked states, there is a third state a checkbox can be in: <strong>indeterminate</strong>. This is a state in which it's impossible to say whether the item is toggled on or off. This is set using the <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement"><code>HTMLInputElement</code></a> object's <code>indeterminate</code> property via JavaScript (it cannot be set using an HTML attribute):</p> <div class="code-example"> +<p class="example-header"><span class="language-name">js</span></p> +<pre data-signature="SKij2w511dy4o0Fae+nEM6zRqUdcgkRb6pXcRcNz/JY=" data-language="js">inputInstance<span class="token punctuation">.</span>indeterminate <span class="token operator">=</span> <span class="token boolean">true</span><span class="token punctuation">;</span> +</pre> +</div> <p>A checkbox in the indeterminate state has a horizontal line in the box (it looks somewhat like a hyphen or minus sign) instead of a check/tick in most browsers.</p> <p>There are not many use cases for this property. The most common is when a checkbox is available that "owns" a number of sub-options (which are also checkboxes). If all of the sub-options are checked, the owning checkbox is also checked, and if they're all unchecked, the owning checkbox is unchecked. If any one or more of the sub-options have a different state than the others, the owning checkbox is in the indeterminate state.</p> <p>This can be seen in the below example (thanks to <a href="https://css-tricks.com/indeterminate-checkboxes/" target="_blank">CSS Tricks</a> for the inspiration). In this example we keep track of the ingredients we are collecting for a recipe. When you check or uncheck an ingredient's checkbox, a JavaScript function checks the total number of checked ingredients:</p> <ul> <li>If none are checked, the recipe name's checkbox is set to unchecked.</li> <li>If one or two are checked, the recipe name's checkbox is set to <code>indeterminate</code>.</li> <li>If all three are checked, the recipe name's checkbox is set to <code>checked</code>.</li> </ul> <p>So in this case the <code>indeterminate</code> state is used to state that collecting the ingredients has started, but the recipe is not yet complete.</p> <div class="code-example"> +<p class="example-header"><span class="language-name">js</span></p> +<pre data-signature="UqPp9nnatHeUWgKbnxV2iDnwfWn5CTQG+NN+cXHwt5o=" data-language="js"><span class="token keyword">const</span> overall <span class="token operator">=</span> document<span class="token punctuation">.</span><span class="token function">querySelector</span><span class="token punctuation">(</span><span class="token string">"#enchantment"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> +<span class="token keyword">const</span> ingredients <span class="token operator">=</span> document<span class="token punctuation">.</span><span class="token function">querySelectorAll</span><span class="token punctuation">(</span><span class="token string">"ul input"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> + +overall<span class="token punctuation">.</span><span class="token function">addEventListener</span><span class="token punctuation">(</span><span class="token string">"click"</span><span class="token punctuation">,</span> <span class="token punctuation">(</span><span class="token parameter">e</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">{</span> + e<span class="token punctuation">.</span><span class="token function">preventDefault</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span> +<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span> + +<span class="token keyword">for</span> <span class="token punctuation">(</span><span class="token keyword">const</span> ingredient <span class="token keyword">of</span> ingredients<span class="token punctuation">)</span> <span class="token punctuation">{</span> + ingredient<span class="token punctuation">.</span><span class="token function">addEventListener</span><span class="token punctuation">(</span><span class="token string">"click"</span><span class="token punctuation">,</span> updateDisplay<span class="token punctuation">)</span><span class="token punctuation">;</span> +<span class="token punctuation">}</span> + +<span class="token keyword">function</span> <span class="token function">updateDisplay</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> + <span class="token keyword">let</span> checkedCount <span class="token operator">=</span> <span class="token number">0</span><span class="token punctuation">;</span> + <span class="token keyword">for</span> <span class="token punctuation">(</span><span class="token keyword">const</span> ingredient <span class="token keyword">of</span> ingredients<span class="token punctuation">)</span> <span class="token punctuation">{</span> + <span class="token keyword">if</span> <span class="token punctuation">(</span>ingredient<span class="token punctuation">.</span>checked<span class="token punctuation">)</span> <span class="token punctuation">{</span> + checkedCount<span class="token operator">++</span><span class="token punctuation">;</span> + <span class="token punctuation">}</span> + <span class="token punctuation">}</span> + + <span class="token keyword">if</span> <span class="token punctuation">(</span>checkedCount <span class="token operator">===</span> <span class="token number">0</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> + overall<span class="token punctuation">.</span>checked <span class="token operator">=</span> <span class="token boolean">false</span><span class="token punctuation">;</span> + overall<span class="token punctuation">.</span>indeterminate <span class="token operator">=</span> <span class="token boolean">false</span><span class="token punctuation">;</span> + <span class="token punctuation">}</span> <span class="token keyword">else</span> <span class="token keyword">if</span> <span class="token punctuation">(</span>checkedCount <span class="token operator">===</span> ingredients<span class="token punctuation">.</span>length<span class="token punctuation">)</span> <span class="token punctuation">{</span> + overall<span class="token punctuation">.</span>checked <span class="token operator">=</span> <span class="token boolean">true</span><span class="token punctuation">;</span> + overall<span class="token punctuation">.</span>indeterminate <span class="token operator">=</span> <span class="token boolean">false</span><span class="token punctuation">;</span> + <span class="token punctuation">}</span> <span class="token keyword">else</span> <span class="token punctuation">{</span> + overall<span class="token punctuation">.</span>checked <span class="token operator">=</span> <span class="token boolean">false</span><span class="token punctuation">;</span> + overall<span class="token punctuation">.</span>indeterminate <span class="token operator">=</span> <span class="token boolean">true</span><span class="token punctuation">;</span> + <span class="token punctuation">}</span> +<span class="token punctuation">}</span> +</pre> +</div> +<iframe width="100%" height="200" src="https://mdn.github.io/learning-area/html/forms/indeterminate-example/index.html" loading="lazy"></iframe> <div class="notecard note" id="sect6"> <p><strong>Note:</strong> If you submit a form with an indeterminate checkbox, the same thing happens as if the checkbox were unchecked — no data is submitted to represent the checkbox.</p> </div> +</div> +<h2 id="validation">Validation</h2> +<div class="section-content"><p>Checkboxes do support <a href="../../constraint_validation">validation</a> (offered to all <a href="../input"><code><input></code></a>s). However, most of the <a href="https://developer.mozilla.org/en-US/docs/Web/API/ValidityState"><code>ValidityState</code></a>s will always be <code>false</code>. If the checkbox has the <a href="../input#required"><code>required</code></a> attribute, but is not checked, then <a href="https://developer.mozilla.org/en-US/docs/Web/API/ValidityState/valueMissing"><code>ValidityState.valueMissing</code></a> will be <code>true</code>.</p></div> +<h2 id="examples">Examples</h2> +<div class="section-content"><p>The following example is an extended version of the "multiple checkboxes" example we saw above — it has more standard options, plus an "other" checkbox that when checked causes a text field to appear to enter a value for the "other" option. This is achieved with a simple block of JavaScript. The example includes implicit labels, with the <code><input></code> directly inside the <code><label></code>. The text input, without a visible label, includes the <a href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label"><code>aria-label</code></a> attribute which provides its accessible name. This example also includes some CSS to improve the styling.</p></div> +<h3 id="html">HTML</h3> +<div class="section-content"><div class="code-example"> +<p class="example-header"><span class="language-name">html</span></p> +<pre data-signature="FMfMKAzRaKlnh2aDzXqJMhuBrf/+1NZ7AlTHYvzlC2A=" 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>fieldset</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>legend</span><span class="token punctuation">></span></span>Choose your interests<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>legend</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 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>checkbox<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>coding<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>interest<span class="token punctuation">"</span></span> <span class="token attr-name">value</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>coding<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span> + Coding + <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>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>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>checkbox<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>music<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>interest<span class="token punctuation">"</span></span> <span class="token attr-name">value</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>music<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span> + Music + <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>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>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>checkbox<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>art<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>interest<span class="token punctuation">"</span></span> <span class="token attr-name">value</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>art<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span> + Art + <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>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>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>checkbox<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>sports<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>interest<span class="token punctuation">"</span></span> <span class="token attr-name">value</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>sports<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span> + Sports + <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>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>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>checkbox<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>cooking<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>interest<span class="token punctuation">"</span></span> <span class="token attr-name">value</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>cooking<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span> + Cooking + <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>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>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>checkbox<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>other<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>interest<span class="token punctuation">"</span></span> <span class="token attr-name">value</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>other<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span> + Other + <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>otherValue<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>other<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>Other interest<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>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 attr-name">type</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>submit<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Submit form<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>fieldset</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></div> +<h3 id="css">CSS</h3> +<div class="section-content"><div class="code-example"> +<p class="example-header"><span class="language-name">css</span></p> +<pre data-signature="Y/lpVTmPtwV5ts5LtgIXJV9xkM1HPQglEIywvRf/HuE=" data-language="css"><span class="token selector">html</span> <span class="token punctuation">{</span> + <span class="token property">font-family</span><span class="token punctuation">:</span> sans-serif<span class="token punctuation">;</span> +<span class="token punctuation">}</span> + +<span class="token selector">form</span> <span class="token punctuation">{</span> + <span class="token property">width</span><span class="token punctuation">:</span> 600px<span class="token punctuation">;</span> + <span class="token property">margin</span><span class="token punctuation">:</span> 0 auto<span class="token punctuation">;</span> +<span class="token punctuation">}</span> + +<span class="token selector">div</span> <span class="token punctuation">{</span> + <span class="token property">margin-bottom</span><span class="token punctuation">:</span> 10px<span class="token punctuation">;</span> +<span class="token punctuation">}</span> + +<span class="token selector">fieldset</span> <span class="token punctuation">{</span> + <span class="token property">background</span><span class="token punctuation">:</span> cyan<span class="token punctuation">;</span> + <span class="token property">border</span><span class="token punctuation">:</span> 5px solid blue<span class="token punctuation">;</span> +<span class="token punctuation">}</span> + +<span class="token selector">legend</span> <span class="token punctuation">{</span> + <span class="token property">padding</span><span class="token punctuation">:</span> 10px<span class="token punctuation">;</span> + <span class="token property">background</span><span class="token punctuation">:</span> blue<span class="token punctuation">;</span> + <span class="token property">color</span><span class="token punctuation">:</span> cyan<span class="token punctuation">;</span> +<span class="token punctuation">}</span> +</pre> +</div></div> +<h3 id="javascript">JavaScript</h3> +<div class="section-content"> +<div class="code-example"> +<p class="example-header"><span class="language-name">js</span></p> +<pre data-signature="AqNCgGYs9qLiJ1nzyulqij8FV+Fo/VMB54Gh93NpFko=" data-language="js"><span class="token keyword">const</span> otherCheckbox <span class="token operator">=</span> document<span class="token punctuation">.</span><span class="token function">querySelector</span><span class="token punctuation">(</span><span class="token string">"#other"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> +<span class="token keyword">const</span> otherText <span class="token operator">=</span> document<span class="token punctuation">.</span><span class="token function">querySelector</span><span class="token punctuation">(</span><span class="token string">"#otherValue"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> +otherText<span class="token punctuation">.</span>style<span class="token punctuation">.</span>visibility <span class="token operator">=</span> <span class="token string">"hidden"</span><span class="token punctuation">;</span> + +otherCheckbox<span class="token punctuation">.</span><span class="token function">addEventListener</span><span class="token punctuation">(</span><span class="token string">"change"</span><span class="token punctuation">,</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">{</span> + <span class="token keyword">if</span> <span class="token punctuation">(</span>otherCheckbox<span class="token punctuation">.</span>checked<span class="token punctuation">)</span> <span class="token punctuation">{</span> + otherText<span class="token punctuation">.</span>style<span class="token punctuation">.</span>visibility <span class="token operator">=</span> <span class="token string">"visible"</span><span class="token punctuation">;</span> + otherText<span class="token punctuation">.</span>value <span class="token operator">=</span> <span class="token string">""</span><span class="token punctuation">;</span> + <span class="token punctuation">}</span> <span class="token keyword">else</span> <span class="token punctuation">{</span> + otherText<span class="token punctuation">.</span>style<span class="token punctuation">.</span>visibility <span class="token operator">=</span> <span class="token string">"hidden"</span><span class="token punctuation">;</span> + <span class="token punctuation">}</span> +<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span> +</pre> +</div> +<div class="code-example" id="sect7"> + +<iframe class="sample-code-frame" title="Examples sample" id="frame_examples" width="100%" height="300" src="https://live.mdnplay.dev/en-US/docs/Web/HTML/Element/input/checkbox/runner.html?id=examples" loading="lazy"></iframe> +</div> +</div> +<h2 id="technical_summary">Technical summary</h2> +<div class="section-content"><figure class="table-container"><div class="_table"><table class="properties"> <tbody> <tr> <td><strong><a href="#value">Value</a></strong></td> <td> A string representing the value of the checkbox. </td> </tr> <tr> <td><strong>Events</strong></td> <td> +<a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event"><code>change</code></a> and <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event"><code>input</code></a> +</td> </tr> <tr> <td><strong>Supported common attributes</strong></td> <td><code>checked</code></td> </tr> <tr> <td><strong>IDL attributes</strong></td> <td> <code><a href="#checked">checked</a></code>, <code><a href="#indeterminate">indeterminate</a></code> and <code><a href="#value">value</a></code> </td> </tr> <tr> <td><strong>DOM interface</strong></td> <td> <p><a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement"><code>HTMLInputElement</code></a></p> </td> </tr> <tr> <td><strong>Methods</strong></td> <td><a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/select"><code>select()</code></a></td> </tr> <tr> <td><strong>Implicit ARIA Role</strong></td> <td><a href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role"><code>checkbox</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/input.html#checkbox-state-(type=checkbox)">HTML Standard <br><small># checkbox-state-(type=checkbox)</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>checkbox</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">1</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">1</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="https://developer.mozilla.org/en-US/docs/Web/CSS/:checked"><code>:checked</code></a>, <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/:indeterminate"><code>:indeterminate</code></a>: CSS selectors that let you style checkboxes based on their current state</li> <li> +<a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement"><code>HTMLInputElement</code></a>: HTML DOM API that implements the <code><input></code> element</li> <li><a href="https://developer.mozilla.org/en-US/docs/Learn/Forms/Property_compatibility_table_for_form_controls">CSS property compatibility table for form controls</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/Element/input/checkbox" class="_attribution-link">https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox</a> + </p> +</div> |