HTML 5

Draft Recommendation — 2 December 2008

4.10 Forms

Forms allow unscripted client-server interaction: given a form, a user can provide data, submit it to the server, and have the server act on it accordingly (e.g. returning the results of a search or calculation). The elements used in forms can also be used for user interaction with no associated submission mechanism, in conjunction with scripts.

Mostly for historical reasons, elements in this section fall into several overlapping (but subtly different) categories in addition to the usual ones like flow content, phrasing content, and interactive content.

A number of the elements are form-associated elements, which means they can have a form owner and, to expose this, have a form content attribute with a matching form DOM attribute.

The form-associated elements fall into several subcategories:

Submittable elements
Denotes elements that can be used for constructing the form data set when a form element is submitted.
Resettable elements
Denotes elements that can be affected when a form element is reset.
Listed
Denotes elements that are listed in the form.elements and fieldset.elements APIs.
Labelable
Denotes elements that can be associated with label elements.

In addition, some submittable elements can be, depending on their attributes, buttons. The prose below defines when an element is a button. Some buttons are specifically submit buttons.

The object amd legend elements are also form-associated elements. With the use of a suitable plugin, the object element can even partake in form submission.

4.10.1 The form element

Categories
Flow content.
Contexts in which this element may be used:
Where flow content is expected.
Content model:
Flow content, but with no form element descendants.
Element-specific attributes:
accept-charset
action
enctype
method
name
novalidate
target
DOM interface:
interface HTMLFormElement : HTMLElement {
           attribute DOMString accept-charset;
           attribute DOMString action;
           attribute DOMString enctype;
           attribute DOMString method;
           attribute DOMString name;
           attribute boolean novalidate;
           attribute DOMString target;

  readonly attribute HTMLFormControlsCollection elements;
  readonly attribute long length;
  [IndexGetter] HTMLElement XXX7(in unsigned long index);
  [NameGetter] Object XXX8(in DOMString name);

  void submit();
  void reset();
  boolean checkValidity();

  void dispatchFormInput();
  void dispatchFormChange();
};

The form element represents a collection of form-associated elements, some of which can represent editable values that can be submitted to a server for processing.

The accept-charset attribute gives the character encodings that are to be used for the submission. If specified, the value must be an ordered set of unique space-separated tokens, and each token must be the preferred name of an ASCII-compatible character encoding. [IANACHARSET]

The name attribute represents the form's name within the forms collection. The value must not be the empty string, and the value must be unique amongst the form elements in the forms collection that it is in, if any.

The action, enctype, method, novalidate, and target attributes are attributes for form submission.

The accept-charset and name DOM attributes must reflect the respective content attributes of the same name.

The elements DOM attribute must return an HTMLFormControlsCollection rooted at the Document node, whose filter matches listed elements whose form owner is the form element, with the exception of input elements whose type attribute is in the Image Button state, which must, for historical reasons, be excluded from this particular collection.

The length DOM attribute must return the number of nodes represented by the elements collection.

The XXX7() method must return the value that would be returned by the item() method of the elements collection if it was invoked with the same arguments.

The XXX8() method must return the value that would be returned by the namedItem() method of the elements collection if it was invoked with the same arguments.

The submit() method, when invoked, must submit the form element from the form element itself.

The reset() method, when invoked, must reset the form element.

If the checkValidity() method is invoked, the user agent must statically validate the constraints of the form element, and return true if the constraint validation return a positive result, and false if it returned a negative result.

If the dispatchFormInput() method is invoked, the user agent must broadcast forminput events from the form element.

If the dispatchFormChange() method is invoked, the user agent must broadcast formchange events from the form element.

4.10.2 The fieldset element

Categories
Flow content.
Listed form-associated element.
Contexts in which this element may be used:
Where flow content is expected.
Content model:
One legend element follwed by flow content.
Element-specific attributes:
disabled
form
name
DOM interface:
interface HTMLFieldSetElement : HTMLElement {
           attribute boolean disabled;
  readonly attribute HTMLFormElement form;
           attribute DOMString name;

  readonly attribute DOMString type;

  readonly attribute HTMLFormControlsCollection elements;

  readonly attribute boolean willValidate;
  readonly attribute ValidityState validity;
  readonly attribute DOMString validationMessage;
  boolean checkValidity();
  void setCustomValidity(in DOMString error);
};

The fieldset element represents a set of form controls grouped under a common name.

The name of the group is given by the first legend element that is a child of the fieldset element. The remainder of the descendants form the group.

The disabled attribute, when specified, causes all the form control descendants of the fieldset element to be disabled.

The form attribute is used to explicitly associate the fieldset element with its form owner. The name attribute represents the element's name.

The disabled DOM attribute must reflect the content attribute of the same name.

The type DOM attribute must return the string "fieldset".

The elements DOM attribute must return an HTMLFormControlsCollection rooted at the fieldset element, whose filter matches listed elements.

The willValidate, validity, and validationMessage attributes, and the checkValidity() and setCustomValidity() methods, are part of the constraint validation API.

Constraint validation: fieldset elements are always barred from constraint validation.

4.10.3 The label element

Categories
Phrasing content.
Interactive content.
Form-associated element.
Contexts in which this element may be used:
Where phrasing content is expected.
Content model:
If the element has a for attribute: Phrasing content, but with no descendant labelable form-associated elements or label elements.
Otherwise: Phrasing content, but with at most one descendant labelable form-associated element, and with no descendant label elements.
Element-specific attributes:
form
for
DOM interface:
interface HTMLLabelElement : HTMLElement {
  readonly attribute HTMLFormElement form;
           attribute DOMString htmlFor;
  readonly attribute HTMLElement control;
};

The label represents a caption in a user interface. The caption can be associated with a specific form control, known as the label element's labeled control.

Unless otherwise specified by the following rules, a label element has no labeled control.

The for attribute may be specified to indicate a form control with which the caption is to be associated. If the attribute is specified, the attribute's value must be the ID of a labelable form-associated element in the same Document as the label element. If the attribute is specified and there is an element in the Document whose ID is equal to the value of the for attribute, and the first such element is a labelable form-associated element, then that element is the label element's labeled control.

If the for attribute is not specified, but the label element has a labelable form-associated element descendant, then the first such descendant in tree order is the label element's labeled control.

The label element's exact default presentation and behavior, in particular what its activation behavior might be, if anything, should match the platform's label behavior.

For example, on platforms where clicking a checkbox label checks the checkbox, clicking the label in the following snippet could trigger the user agent to run synthetic click activation steps on the input element, as if the element itself had been triggered by the user:

<label><input type=checkbox name=lost> Lost</label>

On other platforms, the behavior might be just to focus the control, or do nothing.

The form attribute is used to explicitly associate the label element with its form owner.

The htmlFor DOM attribute must reflect the for content attribute.

The control DOM attribute must return the label element's labeled control, if any, or null if there isn't one.


Labelable form-associated elements have a NodeList object associated with them that represents the list of label elements, in tree order, whose labeled control is the element in question. The labels DOM attribute of labelable form-associated elements, on getting, must return that NodeList object.

4.10.4 The input element

Categories
Phrasing content.
If the type attribute is not in the Hidden state: Interactive content.
Listed, labelable, submittable, and resettable form-associated element.
Contexts in which this element may be used:
Where phrasing content is expected.
Content model:
Empty.
Element-specific attributes:
accept
action
alt
autocomplete
autofocus
checked
disabled
enctype
form
list
max
maxlength
method
min
multiple
name
novalidate
pattern
placeholder
readonly
required
size
src
step
target
type
value
DOM interface:
interface HTMLInputElement : HTMLElement {
           attribute DOMString accept;
           attribute DOMString action;
           attribute DOMString alt;
           attribute boolean autocomplete;
           attribute boolean autofocus;
           attribute boolean defaultChecked;
           attribute boolean checked;
           attribute boolean disabled;
           attribute DOMString enctype;
  readonly attribute HTMLFormElement form;
  readonly attribute HTMLElement list;
           attribute DOMString max;
           attribute long maxLength;
           attribute DOMString method;
           attribute DOMString min;
           attribute boolean multiple;
           attribute DOMString name;
           attribute boolean noValidate;
           attribute DOMString pattern;
           attribute DOMString placeholder;
           attribute boolean readOnly;
           attribute boolean required;
           attribute unsigned long size;
           attribute DOMString src;
           attribute DOMString step;
           attribute DOMString target;
           attribute DOMString type;
           attribute DOMString defaultValue;
           attribute DOMString value;
           attribute DOMTimeStamp valueAsDate;
           attribute float valueAsNumber;
  readonly attribute HTMLOptionElement selectedOption;

  void stepUp(in long n);
  void stepDown(in long n);

  readonly attribute boolean willValidate;
  readonly attribute ValidityState validity;
  readonly attribute DOMString validationMessage;
  boolean checkValidity();
  void setCustomValidity(in DOMString error);

  readonly attribute NodeList labels;
};

The input element represents a typed data field, usually with a form control to allow the user to edit the data.

The type attribute controls the data type (and associated control) of the element. It is an enumerated attribute. The following table lists the keywords and states for the attribute — the keywords in the left column map to the states in the cell in the second column on the same row as the keyword.

Keyword State Data type Control type
hidden Hidden An arbitrary string n/a
text Text Text with no line breaks Text field
search Search Text with no line breaks Search field
url URL An IRI A text field
email E-mail An e-mail address or list of e-mail addresses A text field
password Password Text with no line breaks (sensitive information) Text field that obscures data entry
datetime Date and Time A date and time (year, month, day, hour, minute, second, fraction of a second) with the time zone set to UTC A date and time control
date Date A date (year, month, day) with no time zone A date control
month Month A date consisting of a year and a month with no time zone A month control
week Week A date consisting of a week-year number and a week number with no time zone A week control
time Time A time (hour, minute, seconds, fractional seconds) with no time zone A time control
datetime-local Local Date and Time A date and time (year, month, day, hour, minute, second, fraction of a second) with no time zone A date and time control
number Number A numerical value A text field or spinner control
range Range A numerical value, with the extra semantic that the exact value is not important A slider control or similar
color Color An sRGB color with 8-bit red, green, and blue components A color well
checkbox Checkbox A set of zero or more values from a predefined list A checkbox
radio Radio Button An enumerated value A radio button
file File Upload Zero or more files each with a MIME type and optionally a file name A label and a button
submit Submit Button An enumerated value, with the extra semantic that it must be the last value selected and initiates form submission A button
image Image Button A coordinate, relative to a particular image's size, with the extra semantic that it must be the last value selected and initiates form submission Either a clickable image, or a button
reset Reset Button n/a A button
button Button n/a A button

The missing value default is the Text state.

Which of the accept, action, alt, autocomplete, checked, enctype, and list, max, maxlength, method, min, multiple, novalidate, pattern, readonly, required, size, src, step, and target attributes apply to an input element depends on the state of its type attribute. Similarly, the checked, valueAsDate, valueAsNumber, list, and selectedOption DOM attributes, and the stepUp() and stepDown() methods, are specific to certain states. The following table is non-normative and summarises which content attributes, DOM attrbutes, and methods apply to each state:

Hidden Text, Search, URL E-mail Password Date and Time, Date, Month, Week, Time Local Date and Time, Number Range Color Checkbox, Radio Button File Upload Submit Button Image Button Reset Button, Button
accept · · · · · · · · · Yes · · ·
action · · · · · · · · · · Yes Yes ·
alt · · · · · · · · · · · Yes ·
autocomplete · Yes Yes Yes Yes Yes Yes Yes · · · · ·
checked · · · · · · · · Yes · · · ·
enctype · · · · · · · · · · Yes Yes ·
list · Yes Yes · Yes Yes Yes Yes · · · · ·
max · · · · Yes Yes Yes · · · · · ·
maxlength · Yes Yes Yes · · · · · · · · ·
method · · · · · · · · · · Yes Yes ·
min · · · · Yes Yes Yes · · · · · ·
multiple · · Yes · · · · · · Yes · · ·
novalidate · · · · · · · · · · Yes Yes ·
pattern · Yes Yes Yes · · · · · · · · ·
placeholder · Yes Yes Yes · · · · · · · · ·
readonly · Yes Yes Yes Yes Yes · · · · · · ·
required · Yes Yes Yes Yes Yes · · Yes Yes · · ·
size · Yes Yes Yes · · · · · · · · ·
src · · · · · · · · · · · Yes ·
step · · · · Yes Yes Yes · · · · · ·
target · · · · · · · · · · Yes Yes ·
checked · · · · · · · · Yes · · · ·
value value value value value value value value value default/on · default default default
valueAsDate · · · · Yes · · · · · · · ·
valueAsNumber · · · · Yes Yes Yes · · · · · ·
list · Yes Yes · Yes Yes Yes Yes · · · · ·
selectedOption · Yes Yes · Yes Yes Yes Yes · · · · ·
stepDown() · · · · Yes Yes Yes · · · · · ·
stepUp() · · · · Yes Yes Yes · · · · · ·
input event · Yes Yes Yes Yes Yes Yes Yes Yes · · · ·
change event · Yes Yes Yes Yes Yes Yes Yes Yes Yes · · ·

When an input element's type attribute changes state, and when the element is first created, the element's rendering and behaviour must change to the new state's accordingly and the value sanitization algorithm, if one is defined for the type attribute's new state, must be invoked.

Each input element has a value, which is exposed by the value DOM attribute. Some states define an algorithm to convert a string to a number, an algorithm to convert a number to a string, an algorithm to convert a string to a Date object, and an algorithm to convert a Date object to a string, which are used by max, min, step, valueAsDate, valueAsNumber, stepDown(), and stepUp().

Each input element has a boolean dirty value flag. When it is true, the element is said to have a dirty value. The dirty value flag must be initially set to false when the element is created, and must be set to true whenever the user interacts with the control in a way that changes the value.

The value content attribute gives the default value of the input element. When the value content attribute is added, set, or removed, if the control does not have a dirty value, the user agent must set the value of the element to the value of the value content attribute, if there is one, or the empty string otherwise, and then run the current value sanitization algorithm, if one is defined.

Each input element has a checkedness, which is exposed by the checked DOM attribute.

Each input element has a boolean dirty checkedness flag. When it is true, the element is said to have a dirty checkedness. The dirty checkedness flag must be initially set to false when the element is created, and must be set to true whenever the user interacts with the control in a way that changes the checkedness.

The checked content attribute gives the default checkedness of the input element. When the checked content attribute is added, if the control does not have dirty checkedness, the user agent must set the checkedness of the element to true; when the checked content attribute is removed, if the control does not have dirty checkedness, the user agent must set the checkedness of the element to false.

The reset algorithm for input elements is to set the dirty value flag and dirty checkedness flag back to false, set the value of the element to the value of the value content attribute, if there is one, or the empty string otherwise, set the checkedness of the element to true if the element has a checked content attribute and false if it does not, and then invoke the value sanitization algorithm, if the type attribute's current state defines one.

Each input element has a boolean mutability flag. When it is true, the element is said to be mutable, and when it is false the element is immutable. Unless otherwise specified, an input element is always mutable. Unless otherwise specified, the user agent should not allow the user to modify the element's value or checkedness.

When an input element is disabled, it is immutable.

When an input element does not have a Document node as one of its ancestors (i.e. when it is not in the document), it is immutable.

The readonly attribute can also in some cases make an input element immutable.

The form attribute is used to explicitly associate the input element with its form owner. The name attribute represents the element's name. The disabled attribute is used to make the control non-interactive and to prevent its value from being submitted. The autofocus attribute controls focus.

The accept, alt, autocomplete, max, min, multiple, pattern, placeholder, required, size, src, step, and type DOM attributes must reflect the respective content attributes of the same name. The maxLength DOM attribute must reflect the maxlength content attribute. The readOnly DOM attribute must reflect the readonly content attribute. The defaultChecked DOM attribute must reflect the checked content attribute. The defaultValue DOM attribute must reflect the value content attribute.

The willValidate, validity, and validationMessage attributes, and the checkValidity() and setCustomValidity() methods, are part of the constraint validation API. The labels attribute provides a list of the element's labels.

4.10.4.1 States of the type attribute
4.10.4.1.1 Hidden state

When an input element's type attribute is in the Hidden state, the rules in this section apply.

The input element represents a value that is not intended to be examined or manipulated by the user.

Constraint validation: If an input element's type attribute is in the Hidden state, it is barred from constraint validation.

If the name attribute is present and has a value that is a case-sensitive match for the string "_charset_", then the element's value attribute must be omitted.

The value DOM attribute applies to this element and is in mode value.

The following content attributes must not be specified and do not apply to the element: accept, action, alt, autocomplete, checked, enctype, list, max, maxlength, method, min, multiple, novalidate, pattern, placeholder, readonly, required, size, src, step, and target.

The following DOM attributes and methods do not apply to the element: checked, list, selectedOption, valueAsDate, and valueAsNumber DOM attributes; stepDown() and stepUp() methods.

The input and change events do not apply.

4.10.4.1.2 Text state and Search state

When an input element's type attribute is in the Text state or the Search state, the rules in this section apply.

The input element represents a one line plain text edit control for the element's value.

If the element is mutable, its value should be editable by the user. User agents must not allow users to insert U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR) characters into the element's value.

The value attribute, if specified, must have a value that contains no U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR) characters.

The value sanitization algorithm is as follows: Strip line breaks from the value.

The following common input element content attributes and DOM attributes apply to the element: autocomplete, list, maxlength, pattern, placeholder, readonly, required, and size content attributes; list, selectedOption, and value DOM attributes.

The value DOM attribute is in mode value.

The input and change events apply.

The following content attributes must not be specified and do not apply to the element: accept, action, alt, checked, enctype, max, method, min, multiple, novalidate, src, step, and target.

The following DOM attributes and methods do not apply to the element: checked, valueAsDate, and valueAsNumber DOM attributes; stepDown() and stepUp() methods.

4.10.4.1.3 URL state

When an input element's type attribute is in the URL state, the rules in this section apply.

The input element represents a control for editing a single URL given in the element's value.

If the is mutable, the user agent should allow the user to change the URL represented by its value. User agents may allow the user to set the value to a string that is not a valid URL, but may also or instead automatically escape characters entered by the user so that the value is always a valid URL (even if that isn't the actual value seen and edited by the user in the interface). User agents should allow the user to set the value to the empty string. User agents must not allow users to insert U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR) characters into the value.

The value attribute, if specified, must have a value that is a valid URL.

The value sanitization algorithm is as follows: Strip line breaks from the value.

Constraint validation: While the value of the element is not a valid URL, the element is suffering from a type mismatch.

The following common input element content attributes and DOM attributes apply to the element: autocomplete, list, maxlength, pattern, placeholder, readonly, required, and size content attributes; list, selectedOption, and value DOM attributes.

The value DOM attribute is in mode value.

The input and change events apply.

The following content attributes must not be specified and do not apply to the element: accept, action, alt, checked, enctype, max, method, min, multiple, novalidate, src, step, and target.

The following DOM attributes and methods do not apply to the element: checked, valueAsDate, and valueAsNumber DOM attributes; stepDown() and stepUp() methods.

4.10.4.1.4 E-mail state

When an input element's type attribute is in the E-mail state, the rules in this section apply.

The input element represents a control for editing a list of e-mail addresses given in the element's value.

If the element is mutable, the user agent should allow the user to change the e-mail addresses represented by its value. If the multiple attribute is specified, then the user agent should allow the user to select or provide multiple addresses; otherwise, the user agent should act in a manner consistent with expecting the user to provide a single e-mail address. User agents may allow the user to set the value to a string that is not an valid e-mail address list. User agents should allow the user to set the value to the empty string. User agents must not allow users to insert U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR) characters into the value. User agents may transform the value for display and editing (e.g. converting punycode in the value to IDN in the display and vice versa).

If the multiple attribute is specified on the element, then the value attribute, if specified, must have a value that is a valid e-mail address list; otherwise, the value attribute, if specified, must have a value that is a single valid e-mail address.

The value sanitization algorithm is as follows: Strip line breaks from the value.

Constraint validation: If the multiple attribute is specified on the element, then, while the value of the element is not a valid e-mail address list, the element is suffering from a type mismatch; otherwise, while the value of the element is not a single valid e-mail address, the element is suffering from a type mismatch.

A valid e-mail address list is a set of comma-separated tokens, where each token is itself a valid e-mail address, possibly with one or more leading or trailing space characters.

A valid e-mail address is a string that matches the production dot-atom "@" dot-atom where dot-atom is defined in RFC 2822 section 3.2.4, excluding the CFWS production everywhere. [RFC2822]

The following common input element content attributes and DOM attributes apply to the element: autocomplete, list, maxlength, multiple, pattern, placeholder, readonly, required, and size content attributes; list, selectedOption, and value DOM attributes.

The value DOM attribute is in mode value.

The input and change events apply.

The following content attributes must not be specified and do not apply to the element: accept, action, alt, checked, enctype, max, method, min, novalidate, src, step, and target.

The following DOM attributes and methods do not apply to the element: checked, valueAsDate, and valueAsNumber DOM attributes; stepDown() and stepUp() methods.

4.10.4.1.5 Password state

When an input element's type attribute is in the Password state, the rules in this section apply.

The input element represents a one line plain text edit control for the element's value. The user agent should obscure the value so that people other than the user cannot see it.

If the element is mutable, its value should be editable by the user. User agents must not allow users to insert U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR) characters into the value.

The value attribute, if specified, must have a value that contains no U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR) characters.

The value sanitization algorithm is as follows: Strip line breaks from the value.

The following common input element content attributes and DOM attributes apply to the element: autocomplete, maxlength, pattern, placeholder, readonly, required, and size content attributes; value DOM attribute.

The input and change events apply.

The following content attributes must not be specified and do not apply to the element: accept, action, alt, checked, enctype, list, max, method, min, multiple, novalidate, src, step, and target.

The following DOM attributes and methods do not apply to the element: checked, list, selectedOption, valueAsDate, and valueAsNumber DOM attributes; stepDown() and stepUp() methods.

4.10.4.1.6 Date and Time state

When an input element's type attribute is in the Date and Time state, the rules in this section apply.

The input element represents a control for setting the element's value to a string representing a specific global date and time. User agents may display the date and time in whatever timezone is appropriate for the user.

If the element is mutable, the user agent should allow the user to change the global date and time represented by its value, as obtained by parsing a global date and time from it. User agents must not allow the user to set the value to a string that is not a valid global date and time string expressed in UTC, though user agents may allow the user to set and view the time in another timezone and silently translate the time to and from the UTC timezone in the value. If the user agent provides a user interface for selecting a global date and time, then the value must be set to a valid global date and time string expressed in UTC representing the user's selection. User agents should allow the user to set the value to the empty string.

The value attribute, if specified, must have a value that is a valid global date and time string.

The value sanitization algorithm is as follows: If the value of the element is a valid global date and time string, then adjust the time so that the value represents the same point in time but expressed in the UTC timezone, otherwise, set it to the empty string instead.

The min attribute, if specified, must have a value that is a valid global date and time string. The max attribute, if specified, must have a value that is a valid global date and time string.

The step attribute is expressed in seconds. The step scale factor is 1000 (which converts the seconds to milliseconds, as used in the other algorithms). The default step is 60 seconds.

When the element is suffering from a step mismatch, the user agent may round the element's value to the nearest global date and time for which the element would not suffer from a step mismatch.

The algorithm to convert a string to a number, given a string input, is as follows: If parsing a global date and time from input results in an error, then return an error; otherwise, return the number of milliseconds elapsed from midnight UTC on the morning of 1970-01-01 (the time represented by the value "1970-01-01T00:00:00.0Z") to the parsed global date and time, ignoring leap seconds.

The algorithm to convert a number to a string, given a number input, is as follows: Return a valid global date and time string expressed in UTC that represents the global date and time that is input milliseconds after midnight UTC on the morning of 1970-01-01 (the time represented by the value "1970-01-01T00:00:00.0Z").

The