HTML 5.3

4.10. Forms

4.10.1. Introduction

This section is non-normative.

A form is a component of a Web page that has form controls, such as text fields, buttons, checkboxes, range controls, or color pickers. A user can interact with such a form, providing data that can then be sent to the server for further processing (e.g., returning the results of a search or calculation). No client-side scripting is needed in many cases, though an API is available so that scripts can augment the user experience or use forms for purposes other than submitting data to a server.

Writing a form consists of several steps, which can be performed in any order: writing the user interface, implementing the server-side processing, and configuring the user interface to communicate with the server.

4.10.1.1. Writing a form’s user interface

This section is non-normative.

For the purposes of this brief introduction, we will create a pizza ordering form.

Any form starts with a form element, inside which are placed the controls. Most controls are represented by the input element, which by default provides a one-line text field. To label a control, the label element is used; the label text and the control itself go inside the label element. Each area within a form is typically represented using a div element. Putting this together, here is how one might ask for the customer’s name:

<form>
  <div>
    <label>
      Customer name: <input>
    </label>
  </div>
</form>

To let the user select the size of the pizza, we can use a set of radio buttons. Radio buttons also use the input element, this time with a type attribute with the value radio. To make the radio buttons work as a group, they are given a common name using the name attribute. To group a batch of controls together, such as, in this case, the radio buttons, one can use the fieldset element. The title of such a group of controls is given by the first element in the fieldset, which has to be a legend element. To assist users with entering their names, an autocapitalize attribute with the value of "words" can be added to the input so that user agents are provided a suggestion to automatically capitalize the first character(s) of a user’s entered name.

<form>
  <div>
    <label>
      Customer name: <input autocapitalize="words">
    </label>
  </div>
</form>

<form>
  <div>
    <label>
      Customer name: <input autocapitalize="words">
    </label>
  </div>
  <fieldset>
    <legend>Pizza Size</legend>
    <ul>
      <li>
        <label>
          <input type="radio" name="size"> Small
        </label>
      </li>
      <li>
        <label>
          <input type="radio" name="size"> Large
        </label>
      </li>
    </ul>
  </fieldset>
</form>

To choose toppings, checkboxes can be added to this form. Checkboxes use the input element with a type attribute with the value checkbox:

<form>
  <div>
    <label>
      Customer name: <input autocapitalize="words">
    </label>
  </div>
  <fieldset>
    <legend>Pizza Size</legend>
    <ul>
      <li>
        <label>
          <input type="radio" name="size"> Small
        </label>
      </li>
      <li>
        <label>
          <input type="radio" name="size"> Large
        </label>
      </li>
    </ul>
  </fieldset>
  <fieldset>
    <legend>Pizza Toppings</legend>
    <ul>
      <li>
        <label>
          <input type="checkbox"> Bacon
        </label>
      </li>
      <li>
        <label>
          <input type="checkbox"> Onion
        </label>
      </li>
      <li>
        <label>
          <input type="checkbox"> Mushroom
        </label>
      </li>
    </ul>
  </fieldset>
</form>

In the event there is a problem with a customer’s order, the pizzeria needs a way to be able to collect the customer’s contact information. For this purpose, form controls for telephone numbers (input elements with a type attribute set to tel) and e-mail addresses (input elements with a type attribute set to code>email) can be added:

<form>
  <div>
    <label>
      Customer name: <input autocapitalize="words">
    </label>
  </div>
  <div>
    <label>
      Telephone: <input type="tel">
    </label>
  </div>
  <div>
    <label>
      E-mail: <input type="email">
    </label>
  </div>
  ...
</form>

To let customers request a specific delivery time an input element with its type attribute set to time can be used. Many form controls have attributes to help authors dictate the values a user can enter; in this case, three attributes of particular interest are min, max, and step. Respectively, these set the minimum time, the maximum time, and the interval between allowed values (in seconds).

For this example, the pizzeria only delivers between 11am and 9pm, and allows users to choose a delivery window in 15 minute increments. As the min, max attributes take values in 24-hour time, this means the min value would be "11:00" and the max value would be "21:00". Since the step attribute is set in seconds, to set the form control to accept values in 15 minute increments, the 15 minutes would need to be converted to seconds (900 seconds).

<form>
  ...
  <div>
    <label>
      Preferred delivery time:
      <input type="time" min="11:00" max="21:00" step="900">
    </label>
  </div>
</form>

The textarea element can be used to provide a free-form text field. In this instance, it will allow a space for customers to provide delivery instructions:

<form>
  ...
  <div>
    <label>
      Delivery instructions:
      <textarea></textarea>
    </label>
  </div>
</form>

Finally, to make the form submittable, add a button element:

<form>
  <div>
    <label>
      Customer name: <input autocapitalize="words">
    </label>
  </div>
  <div>
    <label>
      Telephone: <input type="tel">
    </label>
  </div>
  <div>
    <label>
      E-mail: <input type="email">
    </label>
  </div>
  <fieldset>
    <legend>Pizza Size</legend>
    <ul>
      <li>
        <label>
          <input type="radio" name="size"> Small
        </label>
      </li>
      <li>
        <label>
          <input type="radio" name="size"> Large
        </label>
      </li>
    </ul>
  </fieldset>
  <fieldset>
    <legend>Pizza Toppings</legend>
    <ul>
      <li>
        <label>
          <input type="checkbox"> Bacon
        </label>
      </li>
      <li>
        <label>
          <input type="checkbox"> Onion
        </label>
      </li>
      <li>
        <label>
          <input type="checkbox"> Mushroom
        </label>
      </li>
    </ul>
  </fieldset>
  <div>
    <label>
      Preferred delivery time:
      <input type="time" min="11:00" max="21:00" step="900">
    </label>
  </div>
  <div>
    <label>
      Delivery instructions:
      <textarea></textarea>
    </label>
  </div>
  <div>
    <button>Submit order</button>
  </div>
</form>

4.10.1.2. Implementing the server-side processing for a form

This section is non-normative.

The exact details for writing a server-side processor are out of scope for this specification.

For the purposes of this introduction, we will assume that the script at https://pizza.example.com/order is configured to accept submissions using the application/x-www-form-urlencoded format, expecting the following parameters sent in an HTTP POST body:

custname

Customer’s name

custtel

Customer’s telephone number

custemail

Customer’s e-mail

size

The pizza size, either small or large

topping

A topping, specified once for each selected topping, with the allowed values being bacon, onion, and mushroom

delivery

The requested delivery time

comments

The delivery instructions

4.10.1.3. Configuring a form to communicate with a server

This section is non-normative.

Form submissions are exposed to servers in a variety of ways, most commonly as HTTP GET or POST requests. To specify the exact method used, the method attribute is specified on the form element. This doesn’t specify how the form data is encoded, though; to specify that, you use the enctype attribute. You also have to specify the URL of the service that will handle the submitted data, using the action attribute.

For each form control you want submitted, you then have to give a name that will be used to refer to the data in the submission. We already specified the name for the group of radio buttons; the same attribute (name) also specifies the submission name. Radio buttons can be distinguished from each other in the submission by giving them different values, using the value attribute.

Multiple controls can have the same name; for example, here we give all the checkboxes the same name, and the server distinguishes which checkbox was checked by seeing which values are submitted with that name — like the radio buttons, they are also given unique values with the value attribute.

Given the settings in the previous section, this all becomes:

<form method="post" enctype="application/x-www-form-urlencoded" action="https://pizza.example.com/order">
  <div>
    <label>
      Customer name: <input name="custname">
    </label>
  </div>
  <div>
    <label>
      Telephone: <input type="tel" name="custtel">
    </label>
  </div>
  <div>
    <label>
      E-mail: <input type="email" name="custemail">
    </label>
  </div>
  <fieldset>
    <legend>Pizza Size</legend>
    <ul>
      <li>
        <label>
          <input type="radio" name="size"> Small
        </label>
      </li>
      <li>
        <label>
          <input type="radio" name="size"> Large
        </label>
      </li>
    </ul>
  </fieldset>
  <fieldset>
    <legend>Pizza Toppings</legend>
    <ul>
      <li>
        <label>
          <input type="checkbox"> Bacon
        </label>
      </li>
      <li>
        <label>
          <input type="checkbox"> Onion
        </label>
      </li>
      <li>
        <label>
          <input type="checkbox"> Mushroom
        </label>
      </li>
    </ul>
  </fieldset>
  <div>
    <label>
      Preferred delivery time:
      <input type="time" min="11:00" max="21:00" step="900" name="delivery">
    </label>
  </div>
  <div>
    <label>
      Delivery instructions:
      <textarea name="comments"></textarea>
    </label>
  </div>
  <div>
    <button>Submit order</button>
  </div>
</form>

For example, if the customer entered "Denise Lawrence" as their name, "555-555-8642" as their telephone number, did not specify an e-mail, asked for a small pizza, selected the Onion and Mushroom toppings, entered a delivery time of 7pm, and left the delivery instructions text field blank, the user agent would submit the following to the online Web service:

custname=Denise+Lawrence&custtel=555-555-8642&custemail=&size=small&topping=onion&topping=mushroom&delivery=19%3A00&comments=

4.10.1.4. Client-side form validation

This section is non-normative.

Forms can be annotated in such a way that the user agent will check the user’s input before the form is submitted. The server still has to verify the input is valid (since hostile users can easily bypass the form validation), but it allows the user to avoid the wait incurred by having the server be the sole checker of the user’s input.

The simplest annotation is the required attribute, which can be specified on input elements to indicate that the form is not to be submitted until a value is given. By adding this attribute to the customer name, pizza size, and delivery time fields, we allow the user agent to notify the user when the user submits the form without filling in the necessary fields:

<form method="post" enctype="application/x-www-form-urlencoded" action="https://pizza.example.com/order">
  <div>
    <label>
      Customer name: <input name="custname" required>
    </label>
  </div>
  <div>
    <label>
      Telephone: <input type="tel" name="custtel">
    </label>
  </div>
  <div>
    <label>
      E-mail: <input type="email" name="custemail">
    </label>
  </div>
  <fieldset>
    <legend>Pizza Size</legend>
    <ul>
      <li>
        <label>
          <input type="radio" name="size" required> Small
        </label>
      </li>
      <li>
        <label>
          <input type="radio" name="size" required> Large
        </label>
      </li>
    </ul>
  </fieldset>
  <fieldset>
    <legend>Pizza Toppings</legend>
    <ul>
      <li>
        <label>
          <input type="checkbox" name="topping" value="bacon"> Bacon
        </label>
      </li>
      <li>
        <label>
          <input type="checkbox" name="topping" value="onion"> Onion
        </label>
      </li>
      <li>
        <label>
          <input type="checkbox" name="topping" value="mushroom"> Mushroom
        </label>
      </li>
    </ul>
  </fieldset>
  <div>
    <label>
      Preferred delivery time:
      <input type="time" min="11:00" max="21:00" step="900" name="delivery" required>
    </label>
  </div>
  <div>
    <label>
      Delivery instructions:
      <textarea name="comments"></textarea>
    </label>
  </div>
  <div>
    <button>Submit order</button>
  </div>
</form>

It is also possible to limit the length of an input, using the maxlength attribute. By adding this to the textarea element, we can limit users to 1000 characters, preventing them from writing huge essays to the busy delivery drivers instead of staying focused and to the point:

...
  <div>
    <label>
      Delivery instructions:
      <textarea name="comments" maxlength="1000"></textarea>
    </label>
  </div>
  <div>
    <button>Submit order</button>
  </div>
</form>

When a form is submitted, invalid events are fired at each form control that is invalid, and then at the form element itself. This can be useful for displaying a summary of the problems with the form, since typically the browser itself will only report one problem at a time.

4.10.1.5. Enabling client-side automatic filling of form controls

This section is non-normative.

Some browsers attempt to aid the user by automatically filling form controls rather than having the user reenter their information each time. For example, a field asking for the user’s telephone number can be automatically filled with the user’s phone number.

To help the user agent with this, the autocomplete attribute can be used to describe the field’s purpose. In the case of this form, we have three fields that can be usefully annotated in this way: the information about who the pizza is to be delivered to. Adding this information looks like this:

<form method="post" enctype="application/x-www-form-urlencoded" action="https://pizza.example.com/order">
  <div>
    <label>
      Customer name:
      <input name="custname" required autocomplete="shipping name">
    </label>
  </div>
  <div>
    <label>
      Telephone:
      <input type="tel" name="custtel" autocomplete="shipping tel">
    </label>
  </div>
  <div>
    <label>
      E-mail:
      <input type="email" name="custemail" autocomplete="shipping email">
    </label>
  </div>
  ...

4.10.1.6. The difference between the field type, the autofill field name, and the input modality

This section is non-normative.

The type and autocomplete attributes can seem confusingly similar. For instance, in all three cases, the string "email" is a valid value. This section attempts to illustrate the difference between the three attributes and provides advice suggesting how to use them.

The type attribute on input elements decides what kind of control the user agent will use to expose the field. Choosing between different values of this attribute is the same choice as choosing whether to use an input element, a textarea element, a select element, etc.

The autocomplete attribute, in contrast, describes what the value that the user will enter actually represents. Choosing between different values of this attribute is the same choice as choosing what the label for the element will be.

First, consider telephone numbers. If a page is asking for a telephone number from the user, the right form control to use is <input type="tel">. However, which autocomplete value to use depends on which phone number the page is asking for, whether they expect a telephone number in the international format or just the local format, and so forth.

For example, a page that forms part of a checkout process on an e-commerce site for a customer buying a gift to be shipped to a friend might need both the buyer’s telephone number (in case of payment issues) and the friend’s telephone number (in case of delivery issues). If the site expects international phone numbers (with the country code prefix), this could thus look like this:

<p>Please enter complete phone numbers including the country code prefix, as in "+1 555 123 4567".</p>
<div>
  <label>
    Your phone number:
    <input type="tel" name="custtel" autocomplete="billing tel">
  </label>
</div>
<div>
  <label>
    Recipient’s phone number:
    <input type="tel" name="shiptel" autocomplete="shipping tel">
  </label>
</div>

But if the site only supports British customers and recipients, it might instead look like this (notice the use of tel-national rather than tel):

<p>Please enter complete UK phone numbers, as in "(01632) 960 123".</p>
<div>
  <label>
    Your phone number:
    <input type="tel" name="custtel" autocomplete="billing tel-national">
  </label>
</div>
<div>
  <label>
    Recipient’s phone number:
    <input type="tel" name="shiptel" autocomplete="shipping tel-national">
  </label>
</div>

Now, consider a person’s preferred languages. The right autocomplete value is language. However, there could be a number of different form controls used for the purpose: a free text field (<input type="text">), a drop-down list (<select>), radio buttons (<input type="radio">), etc. It only depends on what kind of interface is desired.

4.10.1.7. Date, time, and number formats

This section is non-normative.

In this pizza delivery example, the times are specified in the format "HH:MM": two digits for the hour, in 24-hour format, and two digits for the time. (Seconds could also be specified, though they are not necessary in this example.)

In some locales, however, times are often expressed differently when presented to users. For example, in the United States, it is still common to use the 12-hour clock with an am/pm indicator, as in "2pm". In France, it is common to use the 24-hour clock, and separate the hours from the minutes using an "h" character, as in "14h00".

Similar issues exist with dates, with the added complication that even the order of the components is not always consistent — for example, in Cyprus the first of February 2003 would typically be written "1/2/03", while that same date in Japan would typically be written as "2003年02月01日" — and even with numbers, where locales differ, for example, in what punctuation is used as the decimal separator and the thousands separator.

It is therefore important to distinguish the time, date, and number formats used in HTML and in form submissions, which are always the formats defined in this specification (and based on the well-established ISO 8601 standard for computer-readable date and time formats), from the time, date, and number formats presented to the user by the browser and accepted as input from the user by the browser.

The format used "on the wire", i.e. in HTML markup and in form submissions, is intended to be computer-readable and consistent irrespective of the user’s locale. Dates, for instance, are always written in the format "YYYY-MM-DD", as in "2003-02-01". Users are not expected to ever see this format.

The time, date, or number given by the page in the wire format is then translated to the user’s preferred presentation (based on user preferences or on the locale of the page itself), before being displayed to the user. Similarly, after the user inputs a time, date, or number using their preferred format, the user agent converts it back to the wire format before putting it in the DOM or submitting it.

This allows scripts in pages and on servers to process times, dates, and numbers in a consistent manner without needing to support dozens of different formats, while still supporting the users' needs.

See also the implementation notes regarding localization of form controls.

In places that change from, such as Standard Time to Daylight Saving Time, the same time can occur twice in the same day when the clocks are moved backwards. An input element with a type of datetime-local or time cannot differentiate between two identical instances of time. If this difference matters, applications should allow users to specify which occurrence of the duplicated time they mean, for example by choosing between "Winter time" and "Summer Time".

4.10.2. Categories

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.

• button
• fieldset
• input
• label
• object
• output
• select
• textarea
• img

The form-associated elements fall into several subcategories:

Listed elements

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

• button
• fieldset
• input
• object
• output
• select
• textarea

Submittable elements

Denotes elements that can be used for constructing the form data set when a form element is submitted.

• button
• input
• object
• select
• textarea

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.

Resettable elements

Denotes elements that can be affected when a form element is reset.

• input
• output
• select
• textarea

Reassociateable elements

Denotes elements that have a form content attribute, and a matching form IDL attribute, that allow authors to specify an explicit form owner.

• button
• fieldset
• input
• object
• output
• select
• textarea

Some elements, not all of them form-associated, are categorized as labelable elements. These are elements that can be associated with a label element.

• button
• input (if the type attribute is not in the Hidden state)
• meter
• output
• progress
• select
• textarea

The following table is non-normative and summarizes the above categories of form elements:

4.10.3. The form element

Categories:

Flow content.

Palpable content.

Contexts in which this element can be used:

Where flow content is expected.

Content model:

Flow content, but with no form element descendants.

Tag omission in text/html:

Neither tag is omissible.

Content attributes:

Global attributes

accept-charset - Character encodings to use for §4.10.21 Form submission

action - URL to use for §4.10.21 Form submission

autocomplete - Default setting for autofill feature for controls in the form

enctype - Form data set encoding type to use for §4.10.21 Form submission

method - HTTP method to use for §4.10.21 Form submission

name - Name of form to use in the document.forms API

novalidate - Bypass form control validation for §4.10.21 Form submission

target - browsing context for §4.10.21 Form submission

Allowed ARIA role attribute values:

form (default - do not set), none, presentation or search.

Allowed ARIA state and property attributes:

Global aria-* attributes

Any aria-* attributes applicable to the allowed roles.

DOM interface:

[OverrideBuiltins]
interface HTMLFormElement : HTMLElement {
  attribute DOMString acceptCharset;
  attribute DOMString action;
  attribute DOMString autocomplete;
  attribute DOMString enctype;
  attribute DOMString encoding;
  attribute DOMString method;
  attribute DOMString name;
  attribute boolean noValidate;
  attribute DOMString target;

  [SameObject] readonly attribute HTMLFormControlsCollection elements;
  readonly attribute unsigned long length;
  getter Element (unsigned long index);
  getter (RadioNodeList or Element) (DOMString name);

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

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 content 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 that are ASCII case-insensitive, and each token must be an ASCII case-insensitive match for one of the labels of an ASCII-compatible encoding. [ENCODING]

The name content 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 content 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, form controls in the form will have their autofill field name set to "off"; the on state indicates that by default, form controls in the form will have their autofill field name set to "on".

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

form . elements

Returns an HTMLFormControlsCollection 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).

form[index]

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

form[name]

Returns the form control (or, if there are several, a RadioNodeList of the form controls) in the form with the given ID or name (excluding image buttons for historical reasons); or, if there are none, returns the img element with the given ID.

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 RadioNodeList object containing all those elements is returned.

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 . reportValidity()

Returns true if the form’s controls are all valid; otherwise, returns false and informs the user.

The autocomplete IDL attribute must reflect the content attribute of the same name, limited to only known values.

The name IDL attribute must reflect the content attribute 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 form element, 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 supported property indices at any instant are the indices supported by the object returned by the elements attribute at that instant.

When a form element is indexed for indexed property retrieval, the user agent must return the value returned by the item method on the elements collection, when invoked with the given index as its 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 supported property names consist of the names obtained from the following algorithm, in the order obtained from this algorithm:

1. Let sourced names be an initially empty ordered list of tuples consisting of a string, an element, a source, where the source is either id, name, or past, and, if the source is past, an age.

2. For each listed element candidate whose form owner is the form element, with the exception of any input elements whose type attribute is in the Image Button state, run these substeps:

   1. If candidate has an id attribute, add an entry to sourced names with that id attribute’s value as the string, candidate as the element, and id as the source.
   2. If candidate has a name attribute, add an entry to sourced names with that name attribute’s value as the string, candidate as the element, and name as the source.

3. For each img element candidate whose form owner is the form element, run these substeps:

   1. If candidate has an id attribute, add an entry to sourced names with that id attribute’s value as the string, candidate as the element, and id as the source.
   2. If candidate has a name attribute, add an entry to sourced names with that name attribute’s value as the string, candidate as the element, and name as the source.
4. For each entry past entry in the past names map add an entry to sourced names with the past entry’s name as the string, past entry’s element as the element, past as the source, and the length of time past entry has been in the past names map as the age.
5. Sort sourced names by tree order of the element entry of each tuple, sorting entries with the same element by putting entries whose source is id first, then entries whose source is name, and finally entries whose source is past, and sorting entries with the same element and source by their age, oldest first.
6. Remove any entries in sourced names that have the empty string as their name.
7. Remove any entries in sourced names that have the same name as an earlier entry in the map.
8. Return the list of names from sourced names, maintaining their relative order.

The properties exposed in this way must be unenumerable.

When a form element is indexed for named property retrieval, the user agent must run the following steps:

1. Let candidates be a live RadioNodeList object containing all the listed elements whose form owner is the form element that have either an id attribute or a name attribute equal to name, with the exception of input elements whose type attribute is in the Image Button state, in tree order.

2. If candidates is empty, let candidates be a live RadioNodeList object containing all the img elements that are descendants of the form element and that have either an id attribute or a name attribute equal to name, in tree order.

3. If candidates is empty, 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.

4. If candidates contains more than one node, return candidates and abort these steps.

5. Otherwise, candidates contains exactly one node. Add a mapping from name to the node in candidates in the form element’s past names map, replacing the previous entry with the same name, if any.

6. Return the node in candidates.

If an element listed in a form element’s past names map changes form owner, then its entries must be removed from that map.

The submit() method, when invoked, must submit the form element from the form element itself, with the submitted from submit() method 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 reportValidity() method is invoked, the user agent must interactively 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.

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

<form action="https://www.bing.com/search" method="get">
  <label>
    Bing:
    <input type="search" name="q">
  </label>
  <button type="submit">Search...</button>
</form>

4.10.4. The label element

Categories:

Flow content.

Phrasing content.

Interactive content.

form-associated element.

Palpable content.

Contexts in which this element can be used:

Where phrasing content is expected.

Content model:

Phrasing content, but with no descendant labelable elements unless it is the element’s labeled control, and no descendant label elements.

Tag omission in text/html:

Neither tag is omissible

Content attributes:

Global attributes

for - Associate the label with form control

Allowed ARIA role attribute values:

None

Allowed ARIA state and property attributes:

Global aria-* attributes

DOM interface:

interface HTMLLabelElement : HTMLElement {
  readonly attribute HTMLFormElement? form;
  attribute DOMString htmlFor;
  readonly attribute HTMLElement? control;
};

The label element 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 the 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 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 element, then that element is the label element’s labeled control.

<form>
  <div>
    <label for="fname">
      Full name:
    </label>
    <input type="text" name="fullname" id="fname">
  </div>
  ...
</form>

<form>
  <table>
    <caption>Manage Customers</caption>
    <thead>
      <tr>
        <th>
          Archive
        </th>
        <th>
          Customer Name
        </th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>
          <input type="checkbox" id="c1" name="customer1">
        </td>
        <td>
          <label for="c1">Laura Nelson</label>
        </td>
      </tr>
      <!-- ... -->
    </tbody>
  </table>
  <button type="submit">Archive customers</button>
</form>

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

The label element’s activation behavior should match the platform’s label behavior. Similarly, any additional presentation hints should match the platform’s label presentation.

<div>
  <input type="checkbox" name="lost">
  <label>Lost</label>
</div>
<div>
  <label>Where?</label>
  <input type="text" name="where">
</div>

If a label element has interactive content other than its labeled control, the activation behavior of the label element for events targeted at those interactive content descendants and any descendants of those must be to do nothing.

<!-- bad example - link inside label reduces checkbox activation area -->
<label>
  <input type="checkbox" name="tac">
  I agree to <a href="tandc.html">the terms and conditions</a>
</label>

The ability to click or press a label to trigger an event on a control provides usability and accessibility benefits by increasing the hit area of a control, making it easier for a user to operate. These benefits may be lost or reduced, if the label element contains an element with its own activation behavior, such as a link:

<!-- bad example - all label text inside the link reduces activation area to checkbox only -->
<label>
  <input type="checkbox" name="tac">
  <a href="tandc.html">I agree to the terms and conditions</a>
</label>

<!-- good example - link outside label means checkbox activation area includes the checkbox and all the label text -->
<label>
  <input type="checkbox" name="tac">
  I agree to the terms and conditions
</label>
(read <a href="tandc.html">Terms and Conditions</a>)

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

label . control

Returns the form control that is associated with this element.

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 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 elements, on getting, must return that NodeList object.

4.10.5. The input element

Categories:

Flow content.

Phrasing content.

If the type attribute is not in the Hidden state: interactive content.

If the type attribute is not in the Hidden state: listed, labelable, submittable, resettable, and reassociateable form-associated element.

If the type attribute is in the Hidden state: listed, submittable, resettable, and reassociateable form-associated element.

If the type attribute is not in the Hidden state: Palpable content.

Contexts in which this element can be used:

Where phrasing content is expected.

Content model:

Nothing.

Tag omission in text/html:

No end tag

Content attributes:

Global attributes

accept - Hint for expected file type in File Upload controls

alt - Replacement text for use when images are not available

autocapitalize - Hint for helping to capitalize user input

autocomplete - Hint for form autofill feature

autofocus - Automatically focus the form control when the page is loaded

capture - Specifies the preferred facing mode for the media capture mechanism, defined in [html-media-capture]

checked - Whether the command or control is checked

dirname - Name of form field to use for sending the element’s directionality in §4.10.21 Form submission

disabled - Whether the form control is disabled

form - Associates the control with a form element

formaction - URL to use for §4.10.21 Form submission

formenctype - Form data set encoding type to use for §4.10.21 Form submission

formmethod - HTTP method to use for §4.10.21 Form submission

formnovalidate - Bypass form control validation for §4.10.21 Form submission

formtarget - browsing context for §4.10.21 Form submission

height - Vertical dimension

list - List of autocomplete options

max - Maximum value

maxlength - Maximum length of value

min - Minimum value

minlength - Minimum length of value

multiple - Whether to allow multiple values

name - Name of form control to use for §4.10.21 Form submission and in the form.elements API

pattern - Pattern to be matched by the form control’s value

placeholder - User-visible label to be placed within the form control

readonly - Whether to allow the value to be edited by the user

required - Whether the control is required for §4.10.21 Form submission

size - Size of the control

src - Address of the resource

step - Granularity to be matched by the form control’s value

type - Type of form control

value - Value of the form control

width - Horizontal dimension

Also, the title attribute has special semantics on this element when used in conjunction with the pattern attribute.

Allowed ARIA role attribute values:

Depends upon state of the type attribute.

Allowed ARIA state and property attributes:

Global aria-* attributes

Any aria-* attributes applicable to the allowed roles.

DOM interface:

interface HTMLInputElement : HTMLElement {
  attribute DOMString accept;
  attribute DOMString alt;
  attribute DOMString autocapitalize;
  attribute DOMString autocomplete;
  attribute boolean autofocus;
  attribute boolean defaultChecked;
  attribute boolean checked;
  attribute DOMString dirName;
  attribute boolean disabled;
  readonly attribute HTMLFormElement? form;
  readonly attribute FileList? files;
  attribute DOMString formAction;
  attribute DOMString formEnctype;
  attribute DOMString formMethod;
  attribute boolean formNoValidate;
  attribute DOMString formTarget;
  attribute unsigned long height;
  attribute boolean indeterminate;
  readonly attribute HTMLElement? list;
  attribute DOMString max;
  attribute long maxLength;
  attribute DOMString min;
  attribute long minLength;
  attribute boolean multiple;
  attribute DOMString name;
  attribute DOMString pattern;
  attribute DOMString placeholder;
  attribute boolean readOnly;
  attribute boolean _required;
  attribute unsigned long size;
  attribute DOMString src;
  attribute DOMString step;
  attribute DOMString type;
  attribute DOMString defaultValue;
  [TreatNullAs=EmptyString] attribute DOMString value;
  attribute object? valueAsDate;
  attribute unrestricted double valueAsNumber;
  attribute unsigned long width;

  void stepUp(optional long n = 1);
  void stepDown(optional long n = 1);

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

  [SameObject] readonly attribute NodeList labels;

  void select();
  attribute unsigned long? selectionStart;
  attribute unsigned long? selectionEnd;
  attribute DOMString? selectionDirection;
  void setRangeText(DOMString replacement);
  void setRangeText(DOMString replacement, unsigned long start, unsigned long end, optional SelectionMode selectionMode = "preserve");
  void setSelectionRange(unsigned long start, unsigned long end, optional DOMString direction);
};

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 of the element. It is an enumerated attribute. The data type is used to select the control to use for the input. Some data types allow either a text field or combo box control to be used, based on the absence or presence of a list attribute on the element. The following table lists the keywords and states for the attribute — the keywords in the left column map to the state, data type and control(s) in the cells on the same row.

The missing value default is the Text state.

Which of the accept, alt, autocapitalize, autocomplete, checked, dirname, formaction, formenctype, formmethod, formnovalidate, formtarget, height, list, max, maxlength, min, minlength, multiple, pattern, placeholder, readonly, required, size, src, step, and width content attributes, the checked, files, valueAsDate, valueAsNumber, and list IDL attributes, the select() method, the selectionStart, selectionEnd, and selectionDirection, IDL attributes, the setRangeText() and setSelectionRange() methods, the stepUp() and stepDown() methods, and the input and change events apply to an input element depends on the state of its type attribute. The subsections that define each type also clearly define in normative "bookkeeping" sections which of these feature apply, and which do not apply, to each type. The behavior of these features depends on whether they apply or not, as defined in their various sections (q.v. for Content attributes, for APIs, for events).

The following table is non-normative and summarizes which of those content attributes, IDL attributes, methods, and events apply to each state:

† If the control has no text field, the select() method results in a no-op, with no "InvalidStateError" DOMException.

Some states of the type attribute define a value sanitization algorithm.

Each input element has a value, which is exposed by the value IDL 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. 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. (It is also set to true when the value is programmatically changed, as described in the definition of the value IDL attribute.)

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’s dirty value flag is false, 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 IDL 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 is a boolean attribute that 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, empty the list of selected files, and then invoke the value sanitization algorithm, if the type attribute’s current state defines one.

Each input element can be mutable. Except where otherwise specified, an input element is always mutable. Similarly, except where 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 not mutable.

The readonly attribute can also in some cases (e.g., for the Date state, but not the Checkbox state) stop an input element from being mutable.

The cloning steps for input elements must propagate the value, dirty value flag, checkedness, and dirty checkedness flag from the node being cloned to the copy.

When an input element is first created, the element’s rendering and behavior must be set to the rendering and behavior defined for the type attribute’s state, and the value sanitization algorithm, if one is defined for the type attribute’s state, must be invoked.

The name attribute represents the element’s name. The dirname attribute controls how the element’s directionality is submitted. The disabled attribute is used to make the control non-interactive and to prevent its value from being submitted. The form attribute is used to explicitly associate the input element with its form owner. The autofocus attribute controls focus. The autocapitalize attribute provides a hint for the user agent to help the user automatically capitalize text they enter. The autocomplete attribute controls how the user agent provides autofill behavior.

The indeterminate IDL attribute must initially be set to false. On getting, it must return the last value it was set to. On setting, it must be set to the new value. It has no effect except for changing the appearance of checkbox controls.

The accept, alt, max, min, multiple, pattern, placeholder, required, size, src, and step IDL attributes must reflect the respective content attributes of the same name. The dirName IDL attribute must reflect the dirname content attribute. The readOnly IDL attribute must reflect the readonly content attribute. The defaultChecked IDL attribute must reflect the checked content attribute. The defaultValue IDL attribute must reflect the value content attribute.

The type and autocapitalize IDL attributes must reflect the respective content attributes of the same name, limited to only known values. The maxLength IDL attribute must reflect the maxlength content attribute, limited to only non-negative numbers. The minLength IDL attribute must reflect the minlength content attribute, limited to only non-negative numbers.

The IDL attributes width and height must return the rendered width and height of the image, in CSS pixels, if an image is being rendered, and is being rendered to a visual medium; or else the intrinsic width and height of the image, in CSS pixels, if an image is available but not being rendered to a visual medium; or else 0, if no image is available. When the input element’s type attribute is not in the Image Button state, then no image is available. [CSS-2015]

On setting, they must act as if they reflected the respective content attributes of the same name.

The willValidate, validity, and validationMessage IDL attributes, and the checkValidity(), reportValidity(), and setCustomValidity() methods, are part of the constraint validation API. The labels IDL attribute provides a list of the element’s labels. The select(), selectionStart, selectionEnd, selectionDirection, setRangeText(), and setSelectionRange() methods and IDL attributes expose the element’s text selection. The autofocus, disabled, form, and name IDL attributes are part of the element’s forms API.

4.10.5.1. States of the type attribute

4.10.5.1.1. Hidden state (type=hidden)

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.

4.10.5.1.2. Text (type="text") state and Search state (type="search")

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.

The difference between the Text state and the Search state is primarily stylistic: on platforms where search fields are distinguished from regular text fields, the Search state might result in an appearance consistent with the platform’s search fields rather than appearing like a regular text field.

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.

If the element is mutable, the user agent should allow the user to change the writing direction of the element, setting it either to a left-to-right writing direction or a right-to-left writing direction. If the user does so, the user agent must then run the following steps:

1. Set the element’s dir attribute to "ltr" if the user selected a left-to-right writing direction, and "rtl" if the user selected a right-to-left writing direction.
2. Queue a task to fire a simple event that bubbles named input at the input element.

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.

4.10.5.1.3. Telephone state (type="tel")

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

The input element represents a control for editing a telephone number given in the element’s value.

If the element is mutable, its value should be editable by the user. User agents may change the spacing and, with care, the punctuation of values that the user enters. 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.

Unlike the URL and E-mail types, the Telephone type does not enforce a particular syntax. This is intentional; in practice, telephone number fields tend to be free-form fields, because there are a wide variety of valid phone numbers. Systems that need to enforce a particular format are encouraged to use the pattern attribute or the setCustomValidity() method to hook into the client-side validation mechanism.

4.10.5.1.4. URL state (type="url")

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 absolute URL given in the element’s value.

If the element 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 absolute URL, but may also or instead automatically escape characters entered by the user so that the value is always a valid absolute 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 and not empty, must have a value that is a valid URL potentially surrounded by spaces that is also an absolute URL.

The value sanitization algorithm is as follows: Strip line breaks from the value, then strip leading and trailing white space from the value.

Constraint validation: While the value of the element is neither the empty string nor a valid absolute URL, the element is suffering from a type mismatch.

<input type="url" name="location" list="urls">
<datalist id="urls">
  <option label="MIME: Format of Internet Message Bodies" value="https://tools.ietf.org/html/rfc2045">
  <option label="HTML 4.01 Specification" value="https://www.w3.org/TR/html4/">
  <option label="Form Controls" value="https://www.w3.org/TR/xforms/slice8.html#ui-commonelems-hint">
  <option label="Scalable Vector Graphics (SVG) 1.1 Specification" value="https://www.w3.org/TR/SVG/">
  <option label="Feature Sets - SVG 1.1 - 20030114" value="https://www.w3.org/TR/SVG/feature.html">
  <option label="The Single UNIX Specification, Version 3" value="https://www.unix-systems.org/version3/">
</datalist>

4.10.5.1.5. E-mail state (type="email")

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

User agents may transform the values for display and editing.

User agents should convert punycode in the domain labels of the value to Internationalized Domain Names in the display, and vice versa.

User agents should allow the user to set the value to a string that is not a valid e-mail address or valid e-mail address list.

User agents must not allow users to insert U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR) characters into the value.

Some aspects of how the E-mail state operates depend on whether the multiple attribute is present.

When the multiple attribute is not specified on the element

The input element represents a control for editing an e-mail address given in the element’s value.

If the element is mutable, the user agent should allow the user to change the e-mail address represented by its value, including setting the value to the empty string.

The user agent should act in a manner consistent with expecting the user to provide a single e-mail address.

Constraint validation: While the user interface is representing input that the user agent cannot convert to a valid email address, the control is suffering from bad input.

The value attribute, if specified and not empty, 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, then strip leading and trailing white space from the value.

Constraint validation: While the value of the element is neither the empty string nor a single valid e-mail address, the element is suffering from a type mismatch.

When the multiple attribute is specified on the element

The input element represents a control for adding, removing, and editing a list of e-mail addresses given in the element’s values.

If the element is mutable, the user agent should allow the user to add, remove, and edit the e-mail addresses represented by its values, including removing all addresses and setting the value to the empty string.

User agents may allow the user to set any individual value in the list of values to a string that is not a valid e-mail address, but must not allow users to set any individual value to a string containing U+002C COMMA (,) as well as the U+000A LINE FEED (LF), or U+000D CARRIAGE RETURN (CR) characters.

Constraint validation: While the user interface describes a situation where an individual value contains a U+002C COMMA (,) or is representing input that the user agent cannot convert to a valid email address, the control is suffering from bad input.

Whenever the user changes the element’s values, the user agent must run the following steps:

1. Let latest values be a copy of the element’s values.
2. Strip leading and trailing white space from each value in latest values.
3. Let the element’s value be the result of concatenating all the values in latest values, separating each value from the next by a single U+002C COMMA character (,), maintaining the list’s order.

The value attribute, if specified, must have a value that is a valid e-mail address list.

The value sanitization algorithm is as follows:

1. Split on commas the element’s value, strip leading and trailing white space from each resulting token, if any, and let the element’s values be the (possibly empty) resulting list of (possibly empty) tokens, maintaining the original order.
2. Let the element’s value be the result of concatenating the element’s values, separating each value from the next by a single U+002C COMMA character (,), maintaining the list’s order.

Constraint validation: While the value of the element is not a valid e-mail address list, the element is suffering from a type mismatch.

When the multiple attribute is set or removed, the user agent must run the value sanitization algorithm.

A valid e-mail address is defined in [RFC6531].

A user agent should present and consume Unicode text in the user interface, and expose it to other applications, except when sending to a Mail Transfer Agent that does not support SMTPUTF8 [RFC6531].

A valid e-mail address list is a set of comma-separated tokens, where each token is itself a valid e-mail address. To obtain the list of tokens from a valid e-mail address list, an implementation must split the string on commas.

4.10.5.1.6. Password state (type="password")

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.

4.10.5.1.7. Date state (type="date")

When an input element’s type attribute is in the Date 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 date.

date values represent a "floating" time and do not include time zone information. Care is needed when converting values of this type to or from date data types in JavaScript and other programming languages. In many cases, an implicit time-of-day and time zone are used to create a global ("incremental") time (an integer value that represents the offset from some arbitrary epoch time). Processing or conversion of these values, particularly across time zones, can change the value of the date itself. [TIMEZONE]

If the element is mutable, the user agent should allow the user to change the date represented by its value, as obtained by parsing a date from it. User agents must not allow the user to set the value to a non-empty string that is not a valid date string. If the user agent provides a user interface for selecting a date, then the value must be set to a valid date string representing the user’s selection. User agents should allow the user to set the value to the empty string.

Constraint validation: While the user interface describes input that the user agent cannot convert to a valid date string, the control is suffering from bad input.

See §4.10.1.7 Date, time, and number formats for a discussion of the difference between the input format and submission format for date, time, and number form controls, and the implementation notes regarding localization of form controls.

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

The value sanitization algorithm is as follows: If the value of the element is not a valid date string, then set it to the empty string instead.

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

The step attribute is expressed in days. The step scale factor is 86,400,000 (which converts the days to milliseconds, which is the base unit of comparison for the conversion algorithms below). The default step is 1 day.

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

The change event is fired whenever the user selects a new valid date string. Moving focus away from the date picker component or explicitly confirming with a button are unambigous triggers that the user wants the value changed. The event must be fired on all such cases if the new date value is different than the previous one.

User agents are not required to firing the event on intermediate values reached as the user cycles through a sequence of values. For example, user agents may employ a timeout between changes, to avoid firing too many change events.

The algorithm to convert a string to a number, given a string input, is as follows: If parsing a date 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 midnight UTC on the morning of the parsed date, ignoring leap seconds.

The algorithm to convert a number to a string, given a number input, is as follows: Return a valid date string that represents the date that, in UTC, is current 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 algorithm to convert a string to a Date object, given a string input, is as follows: If parsing a date from input results in an error, then return an error; otherwise, return a new Date object representing midnight UTC on the morning of the parsed date.

The algorithm to convert a Date object to a string, given a Date object input, is as follows: Return a valid date string that represents the date current at the time represented by input in the UTC time zone.

See the note on historical dates in the Local Date and Time state section.

4.10.5.1.8. Month state (type="month")

When an input element’s type attribute is in the Month 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 month.

If the element is mutable, the user agent should allow the user to change the month represented by its value, as obtained by parsing a month from it. User agents must not allow the user to set the value to a non-empty string that is not a valid month string. If the user agent provides a user interface for selecting a month, then the value must be set to a valid month string representing the user’s selection. User agents should allow the user to set the value to the empty string.

Constraint validation: While the user interface describes input that the user agent cannot convert to a valid month string, the control is suffering from bad input.

See §4.10.1.7 Date, time, and number formats for a discussion of the difference between the input format and submission format for date, time, and number form controls, and the implementation notes regarding localization of form controls.

The value attribute, if specified and not empty, must have a value that is a valid month string.

The value sanitization algorithm is as follows: If the value of the element is not a valid month string, then set it to the empty string instead.

The min attribute, if specified, must have a value that is a valid month string. The max attribute, if specified, must have a value that is a valid month string.

The step attribute is expressed in months. The step scale factor is 1 (units of whole months are the base unit of comparison for the conversion algorithms below). The default step is 1 month.

When the element is suffering from a step mismatch, the user agent may round the element’s value to the nearest month 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 month from input results in an error, then return an error; otherwise, return the number of months between January 1970 and the parsed month.

The algorithm to convert a number to a string, given a number input, is as follows: Return a valid month string that represents the month that has input months between it and January 1970.

The algorithm to convert a string to a Date object, given a string input, is as follows: If parsing a month from input results in an error, then return an error; otherwise, return a new Date object representing midnight UTC on the morning of the first day of the parsed month.

The algorithm to convert a Date object to a string, given a Date object input, is as follows: Return a valid month string that represents the month current at the time represented by input in the UTC time zone.

4.10.5.1.9. Week state (type="week")

When an input element’s type attribute is in the Week 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 week beginning on a Monday, at midnight UTC.

If the element is mutable, the user agent should allow the user to change the week represented by its value, as obtained by parsing a week from it. User agents must not allow the user to set the value to a non-empty string that is not a valid week string. If the user agent provides a user interface for selecting a week, then the value must be set to a valid week string representing the user’s selection. User agents should allow the user to set the value to the empty string.

Constraint validation: While the user interface describes input that the user agent cannot convert to a valid week string, the control is suffering from bad input.

See §4.10.1.7 Date, time, and number formats for a discussion of the difference between the input format and submission format for date, time, and number form controls, and the implementation notes regarding localization of form controls.

The value attribute, if specified and not empty, must have a value that is a valid week string.

The value sanitization algorithm is as follows: If the value of the element is not a valid week string, then set it to the empty string instead.

The min attribute, if specified, must have a value that is a valid week string. The max attribute, if specified, must have a value that is a valid week string.

The step attribute is expressed in weeks. The step scale factor is 604,800,000 (which converts the weeks to milliseconds, which is the base unit of comparison for the conversion algorithms below). The default step is 1 week. The default step base is -259,200,000 (the start of week 1970-W01 which is the Monday 3 days before 1970-01-01).

When the element is suffering from a step mismatch, the user agent may round the element’s value to the nearest week 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 week string 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 midnight UTC on the morning of the Monday of the parsed week, ignoring leap seconds.

The algorithm to convert a number to a string, given a number input, is as follows: Return a valid week string that represents the week that, in UTC, is current 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 algorithm to convert a string to a Date object, given a string input, is as follows: If parsing a week from input results in an error, then return an error; otherwise, return a new Date object representing midnight UTC on the morning of the Monday of the parsed week.

The algorithm to convert a Date object to a string, given a Date object input, is as follows: Return a valid week string that represents the week current at the time represented by input in the UTC time zone.

4.10.5.1.10. Time state (type="time")

When an input element’s type attribute is in the 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 time.

If the element is mutable, the user agent should allow the user to change the time represented by its value, as obtained by parsing a time from it. User agents must not allow the user to set the value to a non-empty string that is not a valid time string. If the user agent provides a user interface for selecting a time, then the value must be set to a valid time string representing the user’s selection. User agents should allow the user to set the value to the empty string.

Constraint validation: While the user interface describes input that the user agent cannot convert to a valid time string, the control is suffering from bad input.

See §4.10.1.7 Date, time, and number formats for a discussion of the difference between the input format and submission format for date, time, and number form controls, and the implementation notes regarding localization of form controls.

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

The value sanitization algorithm is as follows: If the value of the element is not a valid time string, then set it to the empty string instead.

The form control has a periodic domain.

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

The step attribute is expressed in seconds. The step scale factor is 1000 (which converts the seconds to milliseconds, which is the base unit of comparison for the conversion algorithms below). 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 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 time from input results in an error, then return an error; otherwise, return the number of milliseconds elapsed from midnight to the parsed time on a day with no time changes.

The algorithm to convert a number to a string, given a number input, is as follows: Return a valid time string that represents the time that is input milliseconds after midnight on a day with no time changes.

The algorithm to convert a string to a Date object, given a string input, is as follows: If parsing a time from input results in an error, then return an error; otherwise, return a new Date object representing the parsed time in UTC on 1970-01-01.

The algorithm to convert a Date object to a string, given a Date object input, is as follows: Return a valid time string that represents the UTC time component that is represented by input.

4.10.5.1.11. Local Date and Time state (type="datetime-local")

When an input element’s type attribute is in the Local 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 Local Date and Time, with no time-zone offset information.

If the element is mutable, the user agent should allow the user to change the date and time represented by its value, as obtained by parsing a date and time from it. User agents must not allow the user to set the value to a non-empty string that is not a valid normalized global date and time string. If the user agent provides a user interface for selecting a Local Date and Time, then the value must be set to a valid normalized global date and time string representing the user’s selection. User agents should allow the user to set the value to the empty string.

Constraint validation: While the user interface describes input that the user agent cannot convert to a valid normalized global date and time string, the control is suffering from bad input.

See §4.10.1.7 Date, time, and number formats for a discussion of the difference between the input format and submission format for date, time, and number form controls, and the implementation notes regarding localization of form controls.

Applications need to use care when working with datetime-local values, since most date time objects (in languages such as JavaScript or server-side languages such as Java) use incremental time values tied to the UTC time zone. Implicit conversion of a floating time value to an incremental time can cause the actual value used to be different from user expectations. For more information, refer to: Working with Time Zones §floating

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

The value sanitization algorithm is as follows: If the value of the element is a valid floating date and time string, then set it to a valid normalized floating date and time string representing the same date and time; otherwise, set it to the empty string instead.

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

The step attribute is expressed in seconds. The step scale factor is 1000 (which converts the seconds to milliseconds, which is the base unit of comparison for the conversion algorithms below). 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 floating 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 date and time from input results in an error, then return an error; otherwise, return the number of milliseconds elapsed from midnight on the morning of 1970-01-01 (the time represented by the value "1970-01-01T00:00:00.0") to the parsed floating 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 normalized floating date and time string that represents the date and time that is input milliseconds after midnight on the morning of 1970-01-01 (the time represented by the value "1970-01-01T00:00:00.0").

<fieldset>
  <legend>Destination</legend>
  <div>
    <label>
      Airport:
      <input type="text" name="to" list="airports">
    </label>
  </div>
  <div>
    <label>
      Departure time:
      <input type="datetime-local" name="totime" step="3600">
    </label>
  </div>
</fieldset>
<datalist id="airports">
  <option value="ATL" label="Atlanta">
  <option value="MEM" label="Memphis">
  <option value="LHR" label="London Heathrow">
  <option value="LAX" label="Los Angeles">
  <option value="FRA" label="Frankfurt">
</datalist>

4.10.5.1.12. Number state (type="number")

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

The input element represents a control for setting the element’s value to a string representing a number.

If the element is mutable, the user agent should allow the user to change the number represented by its value, as obtained from applying the rules for parsing floating-point number values to it. User agents must not allow the user to set the value to a non-empty string that is not a valid floating-point number. If the user agent provides a user interface for selecting a number, then the value must be set to the best representation of the number representing the user’s selection as a floating-point number. User agents should allow the user to set the value to the empty string.

Constraint validation: While the user interface describes input that the user agent cannot convert to a valid floating-point number, the control is suffering from bad input.

The value attribute, if specified and not empty, must have a value that is a valid floating-point number.

The value sanitization algorithm is as follows: If the value of the element is not a valid floating-point number, then set it to the empty string instead.

The min attribute, if specified, must have a value that is a valid floating-point number. The max attribute, if specified, must have a value that is a valid floating-point number.

The step scale factor is 1. The default step is 1 (allowing only integers to be selected by the user, unless the step base has a non-integer value).

When the element is suffering from a step mismatch, the user agent may round the element’s value to the nearest number for which the element would not suffer from a step mismatch. If there are two such numbers, user agents are encouraged to pick the one nearest positive infinity.

The algorithm to convert a string to a number, given a string input, is as follows: If applying the rules for parsing floating-point number values to input results in an error, then return an error; otherwise, return the resulting number.

The algorithm to convert a number to a string, given a number input, is as follows: Return a valid floating-point number that represents input.

<label>
  How much do you want to charge?
  $<input type="number" min="0" step="0.01" name="price">
</label>

The type="number" state is not appropriate for input that happens to only consist of numbers but isn’t strictly speaking a number. For example, it would be inappropriate for credit card numbers or US postal codes. A simple way of determining whether to use type="number" is to consider whether it would make sense for the input control to have a spinbox interface (e.g., with "up" and "down" arrows). Getting a credit card number wrong by 1 in the last digit isn’t a minor mistake, it’s as wrong as getting every digit incorrect. So it would not make sense for the user to select a credit card number using "up" and "down" buttons. When a spinbox interface is not appropriate, type="text" is probably the right choice (possibly with a pattern attribute).

4.10.5.1.13. Range state (type=range)

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

The input element represents a control for setting the element’s value to a string representing a number, but with the caveat that the exact value is not important, letting user agents provide a simpler interface than they do for the Number state.

If the element is mutable, the user agent should allow the user to change the number represented by its value, as obtained from applying the rules for parsing floating-point number values to it. User agents must not allow the user to set the value to a string that is not a valid floating-point number. If the user agent provides a user interface for selecting a number, then the value must be set to a best representation of the number representing the user’s selection as a floating-point number. User agents must not allow the user to set the value to the empty string.

Constraint validation: While the user interface describes input that the user agent cannot convert to a valid floating-point number, the control is suffering from bad input.

The value attribute, if specified, must have a value that is a valid floating-point number.

The value sanitization algorithm is as follows: If the value of the element is not a valid floating-point number, then set it to the best representation, as a floating-point number, of the default value.

The default value is the minimum plus half the difference between the minimum and the maximum, unless the maximum is less than the minimum, in which case the default value is the minimum.

When the element is suffering from an underflow, the user agent must set the element’s value to the best representation, as a floating-point number, of the minimum.

When the element is suffering from an overflow, if the maximum is not less than the minimum, the user agent must set the element’s value to a valid floating-point number that represents the maximum.

When the element is suffering from a step mismatch, the user agent must round the element’s value to the nearest number for which the element would not suffer from a step mismatch, and which is greater than or equal to the minimum, and, if the maximum is not less than the minimum, which is less than or equal to the maximum, if there is a number that matches these constraints. If two numbers match these constraints, then user agents must use the one nearest to positive infinity.

<input type="range" min="0" max="100" step="20" value="50">

<input type="range" min="-100" max="100" value="0" step="10" name="power" list="powers">
<datalist id="powers">
  <option value="0">
  <option value="-30">
  <option value="30">
  <option value="++50">
</datalist>

input[type="range"] { height: 75px; width: 49px; background: #D5CCBB; color: #000; }

<input name="x" type="range" min="100" max="700" step="9.09090909" value="509.090909">

<input type="range" name="a" list="a-values">
<datalist id="a-values">
  <option value="10" label="Low">
  <option value="90" label="High">
</datalist>