HTML5

Draft Standard — Call For Comments — 27 October 2009

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 IDL attribute.

The form-associated elements fall into several subcategories:

Listed

Denotes elements that are listed in the form.elements and fieldset.elements APIs.

Labelable

Denotes elements that can be associated with label elements.

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.

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 element is also a form-associated element and can, with the use of a suitable plugin, 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.
Content attributes:
Global attributes
accept-charset
action
autocomplete
enctype
method
name
novalidate
target
DOM interface:
[OverrideBuiltins]
interface HTMLFormElement : HTMLElement {
           attribute DOMString acceptCharset;
           attribute DOMString action;
           attribute boolean autocomplete;
           attribute DOMString enctype;
           attribute DOMString method;
           attribute DOMString name;
           attribute boolean noValidate;
           attribute DOMString target;

  readonly attribute HTMLFormControlsCollection elements;
  readonly attribute long length;
  caller getter any item(in unsigned long index);
  caller getter any namedItem(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 an ASCII case-insensitive match for the preferred MIME 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 autocomplete attribute is an enumerated attribute. The attribute has two states. The on keyword maps to the on state, and the off keyword maps to the off state. The attribute may also be omitted. The missing value default is the on state. The off state indicates that by default, input elements in the form will have their resulting autocompletion state set to off; the on state indicates that by default, input elements in the form will have their resulting autocompletion state set to on.

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

form . elements

Returns an HTMLCollection of the form controls in the form (excluding image buttons for historical reasons).

form . length

Returns the number of form controls in the form (excluding image buttons for historical reasons).

element = form . item(index)
form[index]
form(index)

Returns the indexth element in the form (excluding image buttons for historical reasons).

element = form . namedItem(name)
form[name]
form(name)

Returns the form control in the form with the given ID or name (excluding image buttons for historical reasons).

Once an element has been referenced using a particular name, that name will continue being available as a way to reference that element in this method, even if the element's actual ID or name changes, for as long as the element remains in the Document.

If there are multiple matching items, then a NodeList object containing all those elements is returned.

Returns null if no element with that ID or name could be found.

form . submit()

Submits the form.

form . reset()

Resets the form.

form . checkValidity()

Returns true if the form's controls are all valid; otherwise, returns false.

form . dispatchFormInput()

Dispatches a forminput event at all the form controls.

form . dispatchFormChange()

Dispatches a formchange event at all the form controls.

The autocomplete and name IDL attributes must reflect the respective content attributes of the same name.

The acceptCharset IDL attribute must reflect the accept-charset content attribute.

The elements IDL 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 IDL attribute must return the number of nodes represented by the elements collection.

The indices of the supported indexed properties at any instant are the indices supported by the object returned by the elements attribute at that instant.

The item(index) method must return the value returned by the method of the same name on the elements collection, when invoked with the same argument.

Each form element has a mapping of names to elements called the past names map. It is used to persist names of controls even when they change names.

The names of the supported named properties are the union of the names currently supported by the object returned by the elements attribute, and the names currently in the past names map.

The namedItem(name) method, when called, must run the following steps:

  1. If name is one of the names of the supported named properties of the object returned by the elements attribute, then run these substeps:

    1. Let candidate be the object returned by the namedItem() method on the object returned by the elements attribute when passed the name argument.

    2. If candidate is an element, then add a mapping from name to candidate in the form element's past names map, replacing the previous entry with the same name, if any.

    3. Return candidate and abort these steps.

  2. Otherwise, name is the name of one of the entries in the form element's past names map: return the object associated with name in that map.

If an element listed in the form element's past names map is removed from the Document, then its entries must be removed from the map.

The submit() method, when invoked, must submit the form element from the form element itself, with the scripted-submit flag set.

The reset() method, when invoked, must run the following steps:

  1. If the form element is marked as locked for reset, then abort these steps.

  2. Mark the form element as locked for reset.

  3. Reset the form element.

  4. Unmark the form element as locked for reset.

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.

This example shows two search forms:

<form action="http://www.google.com/search" method="get">
 <label>Google: <input type="search" name="q"></label> <input type="submit" value="Search...">
</form>
<form action="http://www.bing.com/search" method="get">
 <label>Bing: <input type="search" name="q"></label> <input type="submit" value="Search...">
</form>

4.10.2 The fieldset element

Categories
Flow content.
Sectioning root.
Listed form-associated element.
Contexts in which this element may be used:
Where flow content is expected.
Content model:
Optionally a legend element, followed by flow content.
Content attributes:
Global 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 optionally 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, if any. The remainder of the descendants form the group.

The disabled attribute, when specified, causes all the form control descendants of the fieldset element, excluding those that are descendants of the fieldset element's first legend element child, if any, 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.

fieldset . type

Returns the string "fieldset".

fieldset . elements

Returns an HTMLCollection of the form controls in the element.

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

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

The elements IDL 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.

The following snippet shows a fieldset with a checkbox in the legend that controls whether or not the fieldset is enabled. The contents of the fieldset consist of two required text fields and an optional year/month control.

<fieldset name="clubfields" disabled>
 <legend> <label>
  <input type=checkbox name=club onchange="form.clubfields.disabled = !checked">
  Use Club Card
 </label> </legend>
 <p><label>Name on card: <input name=clubname required></label></p>
 <p><label>Card number: <input name=clubnum required pattern="[-0-9]+"></label></p>
 <p><label>Expiry date: <input name=clubexp type=month></label></p>
</fieldset>

4.10.3 The legend element

Categories
None.
Contexts in which this element may be used:
As the first child of a fieldset element.
Content model:
Phrasing content.
Content attributes:
Global attributes
DOM interface:
interface HTMLLegendElement : HTMLElement {
  readonly attribute HTMLFormElement form;
};

The legend element represents a caption for the rest of the contents of the legend element's parent fieldset element, if any.

legend . form

Returns the element's form element, if any, or null otherwise.

The form IDL attribute's behavior depends on whether the legend element is in a fieldset element or not. If the legend has a fieldset element as its parent, then the form IDL attribute must return the same value as the form IDL attribute on that fieldset element. Otherwise, it must return null.

4.10.4 The label element

Categories
Flow content.
Phrasing content.
Interactive content.
Form-associated element.
Contexts in which this element may be used:
Where phrasing content is expected.
Content model:
Phrasing content, but with no descendant labelable form-associated elements unless it is the element's labeled control, and no descendant label elements.
Content attributes:
Global 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, either using for attribute, or by putting the form control inside the label element itself.

Except where 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. When the labeled control is not being rendered, then the label element's activation behavior must be to do nothing.

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.

label . control

Returns the form control that is associated with this element.

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

The htmlFor IDL attribute must reflect the for content attribute.

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

control . labels

Returns a NodeList of all the label elements that the form control is associated with.

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 IDL attribute of labelable form-associated elements, on getting, must return that NodeList object.

The following example shows three form controls each with a label, two of which have small text showing the right format for users to use.

<p><label>Full name: <input name=fn> <small>Format: First Last</small></label></p>
<p><label>Age: <input name=age type=number min=0></label></p>
<p><label>Post code: <input name=pc> <small>Format: AB12 3CD</small></label></p>