input type="checkbox" Element

Module

The input type="checkbox" element is an inline element declared by the XHTML 1.1 Forms Module

Elements in the Forms Module are:
form | label | textarea | select | optgroup | option | button | fieldset | legend |
input type="button" | input type="checkbox" | input type="file" | input type="hidden" | input type="image" | input type="password" | input type="radio" | input type="reset" | input type="submit" | input type="text"

Description

An input type="checkbox" element may be used within a form to create a checkbox, which may be toggled by the user between a checked and an un-checked state. If the checkbox is to be pre-checked (i.e. checked when the form is first rendered) the input type="checkbox" element should be given the checked attribute.

<label for="terms">I accept the Terms &amp; Conditions above:</label>
<input type="checkbox" name="terms" id="terms" value="yes" /><br />
<label for="emails">Please send me interesting emails:</label>
<input type="checkbox" name="emails" id="emails" value="1" checked="checked" />

The value attribute specifies the value to be sent in the name=value pair to the processing URI if the checkbox is checked when the form is submitted. For example, if the form containing the example checkboxes above were submitted with both buttons checked, two pairs would be submitted to the processing URI: terms=yes and emails=1. For an unchecked checkbox, no pair is sent at all.

Note: Although the value attribute is technically optional - and most browsers will make up a value to send (usually "on") if required - you should always specify a value for your checkboxes. This is based on a note in the W3C HTML 4.01 specifications (*HTML 4.01 value attribute of the input element) which says that the value attribute is optional on input elements except when the type attribute has the value "radio" or "checkbox".

A set of checkboxes, each with the same value for its name attribute, is logically equivalent to a select list with the multiple attribute specified.

<div><fieldset>
<legend>I wish to help on:</legend>
<label for="mon">Monday</label>
<input type="checkbox" name="days" value="1" id="mon" checked="checked" /><br />
<label for="tue">Tuesday</label>
<input type="checkbox" name="days" value="2" id="tue" /><br />
<label for="wed">Wednesday</label>
<input type="checkbox" name="days" value="3" id="wed" checked="checked" /><br />
<label for="thu">Thursday</label>
<input type="checkbox" name="days" value="4" id="thu" /><br />
<label for="fri">Friday</label>
<input type="checkbox" name="days" value="5" id="fri" /><br />
<label for="sat">Saturday</label>
<input type="checkbox" name="days" value="6" id="sat" /><br />
<label for="sun">Sunday</label>
<input type="checkbox" name="days" value="7" id="sun" />
</fieldset></div>

<div>
<label for="days">I wish to help on:</label>
<select id="days" name="days" multiple="multiple" size="4">
  <option value="1" selected="selected">Monday</option>
  <option value="2">Tuesday</option>
  <option value="3" selected="selected">Wednesday</option>
  <option value="4">Thursday</option>
  <option value="5">Friday</option>
  <option value="6">Saturday</option>
  <option value="7">Sunday</option>
</select>
</div>

As shown above, a semantically-significant method to add an overall label to a set of checkboxes, stating their combined purpose, is to use enclose the set within a fieldset element and label it using a legend element. (Appearance, including removal of any border, can be controlled using CSS.) The label element itself serves this purpose for the select list.

See also: input type="radio".

#REQUIRED Attributes

Although the type attribute is not #REQUIRED on the input element, its default value is "text" and so must be present on input type="checkbox".

Specific Attributes

From the Forms Module - the Element's own Module

accesskey [ type Character ]

Key to be pressed which allows the checkbox to be toggled directly from the keyboard

checked [ type Boolean ]

If this attribute is present, the checkbox is initially checked, otherwise it is not (this is its initial value - to which it is returned if the form is reset)

disabled [ type Boolean ]

If this attribute is present, the checkbox is initially disabled - no data is sent to the processing URI for disabled elements when the form is submitted. The user cannot interact with a disabled control.

name [ type CDATA ]

This is the name sent to the processing URI for this checkbox if the checkbox is checked when the form is submitted (if the name attribute is not present, no data will be sent for this element). The value sent (in a name=value pair) is that of the value attribute of this element - but data is sent only for those checkboxes which are checked at the time of submission.

Note: Although technically optional, a note in the *Forms Module DTD says that the name attribute is required on all input elements except "submit" and "reset"

tabindex [ type Number ]

An integer between 0 and 32767 specifying the position of the checkbox in the tabbing order of the document

value [ type CDATA ]

The value to be sent in the name=value pair to the processing URI if this checkbox is checked when the form is submitted.

Note: Although this attribute is optional, and most browsers will make up a value to send (usually "on") if required, you should always specify a value attribute for your checkboxes (ref: *HTML 4.01 value attribute of the input element).

From the Intrinsic Events Module

onblur [ type Script ]

Script to be executed when the element loses focus

onchange [ type Script ]

Script to be executed when the checkbox status is changed from checked to unchecked or vice versa

onfocus [ type Script ]

Script to be executed when the element receives focus

Common Attributes

From the Core Attribute Collection

class [ type NMTOKENS ]

One or more space separated classes

id [ type ID ]

A unique identifier for the element

style [ type CDATA ], from the Style Attribute Module (deprecated)

Element-specific styles

title [ type Text ]

Descriptive title for the element (in some user agents this may appear as a "tooltip" when the mouse hovers over the element)

xmlns [ type URI - #FIXED 'http://www.w3.org/1999/xhtml' ]

XML namespace

From the I18N Attribute Collection

dir [ type Enumeration (ltr | rtl) ], from the Bi-directional Text Module

Left-to-right or right-to-left directionality

xml:lang [ type LanguageCode ]

A language code for the element

From the Events Attribute Collection

All attributes in the Events Attribute Collection are supported:
onclick, ondblclick, onmousedown, onmouseup, onmouseover, onmousemove, onmouseout, onkeypress, onkeydown, onkeyup

Content Model

EMPTY

See Content Model & Nesting for information about Content Model syntax and Nesting Groups.

Valid children of input type="checkbox"

This element is empty and may have no children.

Valid parents of input type="checkbox"

• From the Text Module: abbr, acronym, address, cite, code, dfn, div, em, h1 - h6, kbd, p, q, samp, span, strong, var
• From the Hypertext Module: a
• From the List Module: dd, dt, li
• From the Tables Module: caption, td, th
• From the Forms Module: fieldset, label, legend
• From the Presentation Module: b, big, i, small, sub, sup, tt
• From the Edit Module: del, ins
• From the Bi-directional Text Module: bdo
• From the Object Module: object
• From the Ruby Annotation Module: rb, rt