Form action html что это

Form action html что это

The HTML | action Attribute is used to specify where the form data is to be sent to the server after the submission of the form. It can be used in the <form> element.
Syntax:

Attribute Values:
URL: It is used to specify the URL of the document where the data is to be sent after the submission of the form.
The possible values of the URL are:

• absolute URL: It points to another website link. For Example: www.gfg.org
• relative URL: It is used to point to a file within a webpage. For Example: www.geeksforgeeks.org

Example-1: This Example illustrates the use of action attribute.

HTML Form action Attribute: A How-To Guide

The HTML form action attribute defines what should happen to data when a form is submitted on a web page. The value of the action attribute should be the URL of the web resource that will process the contents of the form.

When building forms and asking data on your site or web application, you’ll often want to do something with your data, right? Here is where the form action attribute comes into play.

Find Your Bootcamp Match

• Career Karma matches you with top tech bootcamps
• Access exclusive scholarships and prep courses

Select your interest
First name

Last name

Email

Phone number

By continuing you agree to our Terms of Service and Privacy Policy, and you consent to receive offers and opportunities from Career Karma by telephone, text message, and email.

You should know the basics of creating a form in HTML. You basically wrap your form contents in the <form> element. In the opening tag there are a couple of attributes we can use, and one of them is the action.

The action attribute is used to specify where we want to send the form data when the form is submitted. So the value of the action is the page that will process the form.

HTML Form Action Attribute

The HTML form action attribute states the URL that will process the contents of a form. You should make sure the web resource to which the action attribute points accepts whatever method you have specified in your “method” attribute.

Let’s take a look at the syntax of the action attribute:

The action attribute appears between our opening <form> tag. This attribute is often used with the method attribute.

By default, the method attribute is set to “get”. This means that your form will send data over an HTTP GET request when it is submitted. You can change the method by specifying “method=’post’” in your opening <form> tag.

Data from a form is sent to the “action” URL when a submit button is clicked.

Form action HTML Example

Let’s take a look at an example:

Above, the action is sending the username and email data to a page named process.html. The username and email data has the input type “text”. We define a button with the input type “submit”. When clicked, this button will send our data to our “action” URL.

Now plug in the form example above in an actual HTML file. Then create another file named process.html in the same folder. This file should have the following contents:

This code defines a simple web page that shows a paragraph of text when the page is loaded. Let’s go back to our web form that we defined earlier and fill it out:

Now click submit. Notice we were automatically taken to process.html page! Then, did you notice the URL bar, what is all that extra data? The data after the “?” symbol are query parameters, and since we specified the request as GET, the data is being passed as query parameters.

With this example you might think this is not very useful. That is true. Usually the action attribute is used to send form contents to server pages. For example, we might use a PHP file named process.php.

This process.php then will do all the magic with data. This page could save our data to a database, or register you to your favorite event, you name it. PHP is a powerful server scripting language, often used in web development. If you ever used WordPress, probably the data being processed is done via PHP.

To learn more about PHP, check out our How to Learn PHP guide.

Is the action Attribute Required?

Back in HTML4, the answer would be yes. Nowadays with HTML5, you are not required to specify an action attribute. If you have a form tag without an action attribute then the data will be sent to its own page.

Why would we do this? With the birth of single page applications (SPA), we might want to process our form data using JavaScript. Or we may want to process our data using another framework such as React / Angular.

If we use Vanilla JavaScript we often do this by adding a JavaScript event listener to when the form has been submitted.

Conclusion

The HTML form action attribute defines what happens to the contents of a form when the form is submitted. The action attribute accepts a URL as an argument.

Are you interested in becoming a web developer? Check out our complete How to Learn HTML guide. You’ll find expert advice on learning HTML as well as a list of top online courses and learning resources.

About us: Career Karma is a platform designed to help job seekers find, research, and connect with job training programs to advance their careers. Learn about the CK publication.

Forms in HTML5

Defines the unique identifier for that button within the form. It allows the server to access each button's value when submitted.

«submit_button»

The name value must be unique within the context of a <form> container.

It can only contain alphanumeric characters a-z A-Z 0-9 and some special characters like — _ … but no space.

value

The value sent to the server when submitting the form.

«primary»

The server will receive the value primary .

Defines the button type.

«submit»

The button sends the form data to the server.

«reset»

The button resets the form.

disabled

Disables the button.

No value required.

autofocus

Sets focus on the element when the web page loads.

No value required.

# fieldset

Defines a group of controls within a form.

Example: Copy

disabled

Disables the controls the fieldset contains.

No value required.

Defines an interactive form with controls.

Example: Copy

action

Defines which URL the form's information is sent to when submitted.

«/contact»

You can use a relative URL.

«https://htmlreference.io/contact»

You can use an absolute URL.

method

Defines the HTTP method used when submitting the form.

The form information is sent to the server as part of the request body.

The form information is sent to the server as part URL parameters: /contact?first_name=Alex&last_name=Smith .

The form's name when sent to the server. Useful when multiple forms are present on the same web page.

«sign_up_form»

The name value must be unique within the context of the whole web page.

It can only contain alphanumeric characters a-z A-Z 0-9 and some special characters like — _ … but no space.

autocomplete

Determines if the browser can autocomplete all the form's controls.

The browser will disable autocomplete functions. This can however be overriden for each control individually.

The browser will enable autocomplete functions. This can however be overriden for each control individually.

Try pressing "down" in this input. It will show previously entered email addresses.

target

Defines in which tab or window the clicked link will show up.

«_blank»

Opens in a new browsing context, which is usually a new tab.

«_self»

Opens in the current tab.

«_parent»

Opens in the parent browsing context, or _self is there is none.

Opens in the top browsing context, or _self is there is none.

enctype

Defines the MIME type of the information sent to the server. Only works if the method is post .

«application/x-www-form-urlencoded»

The default value.

«text/plain»

For HTML5 plain text.

«multipart/form-data»

Needed when using an <input type="file"> element.

novalidate

Tells the browser to not validate the form on submission.

No value required.

# input

Defines an interactive control within a web form.

Example: Copy

Defines the type of form input.

Required.

Simple single line text input that accepts any type of character

«email»

Like a text input, but the browser will try to only allow valid email addresses.

On mobile devices, the email keyboard will show up.

«number»

Like a text input, but the browser will try to only allow valid numbers.

On mobile devices, the number keyboard will show up.

«checkbox»

A toggle checkbox that can only be one of two states: checked or unchecked. The value is only submitted by the form if the checkbox is checked.

You can wrap a checkbox in a label, to increase the click area.

Notice how clicking the text toggles the checkbox.

«radio»

Needs to be used used in combination with other radio buttons, so that they are mutually exclusive.

You link radio buttons through a similar name value:

Notice how clicking one deselects the other.

«submit»

Submit button that is triggered when clicked or when pressing Enter.

Defines the unique identifier for that input within the form. It allows the server to access each input's value when submitted.

Required.

«first_name»

The name value must be unique within the context of a <form> container.

It can only contain alphanumeric characters a-z A-Z 0-9 and some special characters like — _ … but no space.

placeholder

Defines a non-selectable placeholder text that only appears when the input is empty.

«e.g. [email protected]»

You can hint at the format expected for the input.

As a best practice, it is recommended to have a label to describe the input, and use the placeholder to showcase an example:

Notice how the placeholder disappears on focus, hence the need to maintain a separate label.

required

Tells the browser that this input is required. Leaving it empty will show a warning.

No value required.

You simply need to add the required attribute with no value:

The browser should show a warning if you try to submit the form with an empty text input.

disabled

Disables the input.

No value required.

# legend

Defines a caption for a parent's content.

Example: Copy

# textarea

Defines a multi-line text control within a web form.

Defines the unique identifier for that textarea within the form. It allows the server to access each textarea's value when submitted.

Required.

«message»

The name value must be unique within the context of a <form> container.

It can only contain alphanumeric characters a-z A-Z 0-9 and some special characters like — _ … but no space.

autocomplete

Determines if the browser can autocomplete the textarea.

The browser will disable autocomplete functions..

The browser will enable autocomplete functions.

minlength

Defines the minimum amount of characters the textarea required to be valid.

You can use integers.

maxlength

Defines the maxlength amount of characters allowed.

You can use integers.

placeholder

Defines a non-selectable placeholder text that only appears when the textarea is empty.

«e.g. Hello my name is Alex»

You can hint at the format expected for the textarea.

Defines the number of columns.

You can use integers.

Defines the number of rows.

You can use integers.

Defines how the text should be wrapped.

The text will always be wrapped depending on the cols value.

The text will only break when needed.

disabled

Disables the textarea.

No value required.

required

Tells the browser that this textarea is required. Leaving it empty will show a warning.

HTML5

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 part of a form is considered a paragraph, and is typically separated from other parts using p elements. Putting this together, here is how one might ask for the customer’s name:

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.

Changes from the previous step are highlighted.

To pick toppings, we can use checkboxes. These use the input element with a type attribute with the value checkbox :

The pizzeria for which this form is being written is always making mistakes, so it needs a way to contact the customer. For this purpose, we can use form controls specifically for telephone numbers ( input elements with their type attribute set to tel ) and e-mail addresses ( input elements with their type attribute set to email ):

We can use an input element with its type attribute set to time to ask for a delivery time. Many of these form controls have attributes to control exactly what values can be specified; in this case, three attributes of particular interest are min , max , and step . These set the minimum time, the maximum time, and the interval between allowed values (in seconds). This pizzeria only delivers between 11am and 9pm, and doesn’t promise anything better than 15 minute increments, which we can mark up as follows:

The textarea element can be used to provide a free-form text field. In this instance, we are going to use it to provide a space for the customer to give delivery instructions:

Finally, to make the form submittable we use the button element:

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.cgi 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 address size The pizza size, either small , medium , or large topping A topping, specified once for each selected topping, with the allowed values being bacon , cheese , 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:

There is no particular significance to the way some of the attributes have their values quoted and others don’t. The HTML syntax allows a variety of equally valid ways to specify attributes, as discussed in the syntax section.

For example, if the customer entered «Denise Lawrence» as their name, «555-321-8642» as their telephone number, did not specify an e-mail address, asked for a medium-sized pizza, selected the Extra Cheese 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:

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 those fields:

It is also possible to limit the length of the 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:

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

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.

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

The form-associated elements fall into several subcategories:

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

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

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

• button
• input
• keygen
• object
• select
• textarea

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

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

• input
• keygen
• output
• select
• textarea

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
• keygen
• label
• object
• output
• select
• textarea

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

4.10.3 The element

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 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 character encoding. [ENCODING]

The 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 attribute is an enumerated attribute. The attribute has two states. The on keyword maps to the state, and the off keyword maps to the 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 «.

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

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

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

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.

Submits the form.

Resets the form.

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

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

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

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

The IDL attribute must return an HTMLFormControlsCollection rooted at the Document node while the form element is in a Document and rooted at the form element itself when it is not, 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 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 , 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 . 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:

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:

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

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.

The properties exposed in this way must not be enumerable.

When a form element is , the user agent must run the following steps:

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

element collection to match new names when elements are renamed, and there are enough pages that rename elements and then access them by their old name that we have to support this. But we still want to expose them using the new names, so as far as possible we pretend the legacy names aren’t there except if there’s no other element actually named that way. Removing the element did remove the legacy name in IE7: http://software.hixie.ch/utilities/js/live-dom-viewer/?%3C!DOCTYPE%20html%3E. %3Cform%20action%3D%22%2F%22%3E%3Cinput%20name%3Dsubmit%3E%3C%2Fform%3E%0A%3Cscript%3E%0A%20w(document.forms%5B0%5D.submit)%3B%0A%20w(document.forms%5B0%5D.removeChild(document.getElementsByTagName(‘input’)%5B0%5D))%3B%0A%20w(document.forms%5B0%5D.length)%3B%0A%20try%20%7B%20document.forms%5B0%5D.submit()%3B%20%7D%20catch%20(e)%20%20%7B%20w(e.message)%20%7D%0A%3C%2Fscript%3E There’s no interop on what happens when the name was originally a duplicate name, so we don’t persist such accesses — at the time of writing, Safari returned the first element, Firefox returned null (as we do), and IE7 returned the original collection: http://software.hixie.ch/utilities/js/live-dom-viewer/?%3C!DOCTYPE%20html%3E. %3Cform%20action%3D%22%2F%22%3E%3Cinput%20name%3Da%20id%3Dfirst%3E%3Cinput%20name%3Da%20id%3Dsecond%3E%3C%2Fform%3E%0A%3Cscript%3E%0A%20w%28document.forms[0].a%29%3B%0A%20document.getElementsByTagName%28%27input%27%29[0].name%20%3D%20%27b%27%3B%0A%20document.getElementsByTagName%28%27input%27%29[1].name%20%3D%20%27b%27%3B%0A%20w%28document.forms[0].length%29%3B%0A%20w%28document.forms[0].a.id%29%3B%0A%3C%2Fscript%3E In addition, the fallback nonsense is similarly here for legacy reasons. As is the exclusion of . Also, check these out: http://software.hixie.ch/utilities/js/live-dom-viewer/saved/1220 http://software.hixie.ch/utilities/js/live-dom-viewer/saved/2388 —>

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

The method, when invoked, must run the following steps:

If the 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.

This example shows two search forms:

4.10.4 The element

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 , 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 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.

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 exact default presentation and behavior, in particular what its activation behavior might be, if anything, should match the platform’s label behavior. The activation behavior of a label element for events targeted at interactive content descendants of a label element, and any descendants of those interactive content descendants, 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:

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

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

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

Returns the form control that is associated with this element.

The IDL attribute must reflect the for content attribute.

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

The form IDL attribute is part of the element’s forms API.

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

4.10.5 The element

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

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

The missing value default is the Text state.

Which of the accept , alt , 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 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 , 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:

Some states of the type attribute define a .

Each input element has a value, which is exposed by the value IDL attribute. Some states define an , an , an , and an , which are used by max , min , step , valueAsDate , valueAsNumber , stepDown() , and stepUp() .

Each input element has a boolean . 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 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 . When it is true, the element is said to have a . 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 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.

When an input element’s type attribute changes state, the user agent must run the following steps:

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 autocomplete attribute controls how the user agent provides autofill behavior.

The 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 , , , , , , , , , , and IDL attributes must reflect the respective content attributes of the same name. The IDL attribute must reflect the dirname content attribute. The IDL attribute must reflect the readonly content attribute. The IDL attribute must reflect the checked content attribute. The IDL attribute must reflect the value content attribute.

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

The IDL attributes and 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]

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() , and setCustomValidity() methods, are part of the constraint validation API. The labels IDL attribute provides a list of the element’s label s. 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 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.

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

4.10.5.1.2 ( type=text ) state and 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 «LF» (U+000A) or «CR» (U+000D) 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:

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

The following common input element content attributes, IDL attributes, and methods apply to the element: autocomplete , dirname , list , maxlength , minlength , pattern , placeholder , readonly , required , and size content attributes; list , selectionStart , selectionEnd , selectionDirection , and value IDL attributes; select() , setRangeText() , and setSelectionRange() methods.

The value IDL attribute is in mode value.

The following content attributes must not be specified and do not apply to the element: accept , alt , checked , formaction , formenctype , formmethod , formnovalidate , formtarget , height , max , min , multiple , src , step , and width .

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

4.10.5.1.3 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 «LF» (U+000A) or «CR» (U+000D) characters into the element’s value.

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

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.

The following common input element content attributes, IDL attributes, and methods apply to the element: autocomplete , list , maxlength , minlength , pattern , placeholder , readonly , required , and size content attributes; list , selectionStart , selectionEnd , selectionDirection , and value IDL attributes; select() , setRangeText() , and setSelectionRange() methods.

The value IDL attribute is in mode value.

The following content attributes must not be specified and do not apply to the element: accept , alt , checked , dirname , formaction , formenctype , formmethod , formnovalidate , formtarget , height , max , min , multiple , src , step , and width .

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

4.10.5.1.4 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 «LF» (U+000A) or «CR» (U+000D) 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.

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.

The following common input element content attributes, IDL attributes, and methods apply to the element: autocomplete , list , maxlength , minlength , pattern , placeholder , readonly , required , and size content attributes; list , selectionStart , selectionEnd , selectionDirection , and value IDL attributes; select() , setRangeText() , and setSelectionRange() methods.

The value IDL attribute is in mode value.

The following content attributes must not be specified and do not apply to the element: accept , alt , checked , dirname , formaction , formenctype , formmethod , formnovalidate , formtarget , height , max , min , multiple , src , step , and width .

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

If a document contained the following markup:

. and the user had typed » www.w3 «, and the user agent had also found that the user had visited http://www.w3.org/Consortium/#membership and http://www.w3.org/TR/XForms/ in the recent past, then the rendering might look like this:

The first four URLs in this sample consist of the four URLs in the author-specified list that match the text the user has entered, sorted in some UA-defined manner (maybe by how frequently the user refers to those URLs). Note how the UA is using the knowledge that the values are URLs to allow the user to omit the scheme part and perform intelligent matching on the domain name.

The last two URLs (and probably many more, given the scrollbar’s indications of more values being available) are the matches from the user agent’s session history data. This data is not made available to the page DOM. In this particular case, the UA has no titles to provide for those values.

4.10.5.1.5 state ( type=email )

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

How the E-mail state operates depends on whether the multiple attribute is specified or not.

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. User agents may allow the user to set the value to a string that is not a valid e-mail address. The user agent should act in a manner consistent with expecting the user to provide a single e-mail address. User agents should allow the user to set the value to the empty string. User agents must not allow users to insert «LF» (U+000A) or «CR» (U+000D) characters into the value. User agents may transform the value for display and editing; in particular, user agents should convert punycode in the value to IDN in the display and vice versa.

Constraint validation: While the user interface is representing input that the user agent cannot convert to punycode, 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.

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

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.

The element’s values are the result of splitting on commas the element’s value.

The input element represents a control for adding, removing, and editing the 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. 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), «LF» (U+000A), or «CR» (U+000D) characters. User agents should allow the user to remove all the addresses in the element’s values. User agents may transform the values for display and editing; in particular, user agents should convert punycode in the value to IDN in the display and vice versa.

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

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

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

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

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

A is a string that matches the email production of the following ABNF, the character set for which is Unicode. This ABNF implements the extensions described in RFC 1123. [ABNF] [RFC5322] [RFC1034] [RFC1123]

This requirement is a willful violation of RFC 5322, which defines a syntax for e-mail addresses that is simultaneously too strict (before the «@» character), too vague (after the «@» character), and too lax (allowing comments, whitespace characters, and quoted strings in manners unfamiliar to most users) to be of practical use here.

The following JavaScript- and Perl-compatible regular expression is an implementation of the above definition.

A 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, and implementation must split the string on commas.

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

input element content attributes, IDL attributes, and methods apply to the element when the multiple attribute is not specified: .

The value IDL attribute is in mode value.

The following content attributes must not be specified and do not apply to the element: accept , alt , checked , dirname , formaction , formenctype , formmethod , formnovalidate , formtarget , height , max , min , src , step , and width .

4.10.5.1.6 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 «LF» (U+000A) or «CR» (U+000D) characters into the value.

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

The following common input element content attributes, IDL attributes, and methods apply to the element: autocomplete , maxlength , minlength , pattern , placeholder , readonly , required , and size content attributes; selectionStart , selectionEnd , selectionDirection , and value IDL attributes; select() , setRangeText() , and setSelectionRange() methods.

The value IDL attribute is in mode value.

The following content attributes must not be specified and do not apply to the element: accept , alt , checked , dirname , formaction , formenctype , formmethod , formnovalidate , formtarget , height , list , max , min , multiple , src , step , and width .

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

4.10.5.1.7 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.

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 the introduction section 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, as used in the other algorithms). 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 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.

The following common input element content attributes, IDL attributes, and methods apply to the element: autocomplete , list , max , min , readonly , required , and step content attributes; list , value , valueAsDate , and valueAsNumber IDL attributes; stepDown() and stepUp() methods.

The value IDL attribute is in mode value.

The following IDL attributes and methods do not apply to the element: checked , selectionStart , selectionEnd , and selectionDirection IDL attributes; select() , setRangeText() , and setSelectionRange() methods.

4.10.5.1.8 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 the introduction section 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 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, as used in the other algorithms). The default step is 60 seconds.

When the element is suffering from a step mismatch, the user agent may round the element’s value to the nearest 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 .

The following common input element content attributes, IDL attributes, and methods apply to the element: autocomplete , list , max , min , readonly , required , and step content attributes; list , value , valueAsDate , and valueAsNumber IDL attributes; stepDown() and stepUp() methods.

The value IDL attribute is in mode value.

The following IDL attributes and methods do not apply to the element: checked , files , selectionStart , selectionEnd , and selectionDirection IDL attributes; select() , setRangeText() , and setSelectionRange() methods.

4.10.5.1.9 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.

This specification does not define what user interface user agents are to use; user agent vendors are encouraged to consider what would best serve their users’ needs. For example, a user agent in Persian or Arabic markets might support Persian and Arabic numeric input (converting it to the format required for submission as described above). Similarly, a user agent designed for Romans might display the value in Roman numerals rather than in decimal; or (more realistically) a user agent designed for the French market might display the value with apostrophes between thousands and commas before the decimals, and allow the user to enter a value in that manner, internally converting it to the submission format described above.

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 .

The following common input element content attributes, IDL attributes, and methods apply to the element: autocomplete , list , max , min , placeholder , readonly , required , and step content attributes; list , value , and valueAsNumber IDL attributes; stepDown() and stepUp() methods.

The value IDL attribute is in mode value.

Here is an example of using a numeric input control:

As described above, a user agent might support numeric input in the user’s local format, converting it to the format required for submission as described above. This might include handling grouping separators (as in «872,000,000,000») and various decimal separators (such as «3,99» vs «3.99») or using local digits (such as those in Arabic, Devanagari, Persian, and Thai).

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.10 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 UAs provide a simpler interface than they do for the Number state.

In this state, the range and step constraints are enforced even during user input, and there is no way to set the value to the empty string.

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 a valid floating-point number that represents the default value.

The min attribute, if specified, must have a value that is a valid floating-point number. The default minimum is 0. The max attribute, if specified, must have a value that is a valid floating-point number. The default maximum is 100.

The 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 a valid floating-point number that represents 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.

The step scale factor is 1. The default step is 1 (allowing only integers, unless the min attribute has a non-integer value).

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.

For example, the markup <input type=»range» min=0 max=100 step=20 value=50> results in a range control whose initial value is 60.

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 .

The following common input element content attributes, IDL attributes, and methods apply to the element: autocomplete , list , max , min , and step content attributes; list , value , and valueAsNumber IDL attributes; stepDown() and stepUp() methods.

The value IDL attribute is in mode value.

Here is an example of a range control using an autocomplete list with the list attribute. This could be useful if there are values along the full range of the control that are especially important, such as preconfigured light levels or typical speed limits in a range control used as a speed control. The following markup fragment:

. with the following style sheet applied:

. might render as:

Note how the UA determined the orientation of the control from the ratio of the style-sheet-specified height and width properties. The colors were similarly derived from the style sheet. The tick marks, however, were derived from the markup. In particular, the step attribute has not affected the placement of tick marks, the UA deciding to only use the author-specified completion values and then adding longer tick marks at the extremes.

Note also how the invalid value ++50 was completely ignored.

For another example, consider the following markup fragment:

A user agent could display in a variety of ways, for instance:

Or, alternatively, for instance:

The user agent could pick which one to display based on the dimensions given in the style sheet. This would allow it to maintain the same resolution for the tick marks, despite the differences in width.

Finally, here is an example of a range control with two labeled values:

With styles that make the control draw vertically, it might look as follows:

4.10.5.1.11 state ( type=color )

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

The input element represents a color well control, for setting the element’s value to a string representing a simple color.

In this state, there is always a color picked, and there is no way to set the value to the empty string.

If the element is mutable, the user agent should allow the user to change the color represented by its value, as obtained from applying the rules for parsing simple color values to it. User agents must not allow the user to set the value to a string that is not a valid lowercase simple color. If the user agent provides a user interface for selecting a color, then the value must be set to the result of using the rules for serializing simple color values to the user’s selection. 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 lowercase simple color, the control is suffering from bad input.

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

The value sanitization algorithm is as follows: If the value of the element is a valid simple color, then set it to the value of the element converted to ASCII lowercase; otherwise, set it to the string » #000000 «.

The following common input element content attributes and IDL attributes apply to the element: autocomplete and list content attributes; list and value IDL attributes.

The value IDL attribute is in mode value.

4.10.5.1.12 state ( type=checkbox )

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

The input element represents a two-state control that represents the element’s checkedness state. If the element’s checkedness state is true, the control represents a positive selection, and if it is false, a negative selection. If the element’s indeterminate IDL attribute is set to true, then the control’s selection should be obscured as if the control was in a third, indeterminate, state.

The control is never a true tri-state control, even if the element’s indeterminate IDL attribute is set to true. The indeterminate IDL attribute only gives the appearance of a third state.

If the element is mutable, then: The pre-click activation steps consist of setting the element’s checkedness to its opposite value (i.e. true if it is false, false if it is true), and of setting the element’s indeterminate IDL attribute to false. The canceled activation steps consist of setting the checkedness and the element’s indeterminate IDL attribute back to the values they had before the pre-click activation steps were run. The activation behavior is to fire a simple event that bubbles named input at the element and then fire a simple event that bubbles named change at the element.

If the element is not mutable, it has no activation behavior.

Constraint validation: If the element is required and its checkedness is false, then the element is suffering from being missing.

When set, overrides the rendering of checkbox controls so that the current value is not visible.

The following common input element content attributes and IDL attributes apply to the element: checked , and required content attributes; checked and value IDL attributes.

The value IDL attribute is in mode default/on.

4.10.5.1.13 state ( type=radio )

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

The input element represents a control that, when used in conjunction with other input elements, forms a radio button group in which only one control can have its checkedness state set to true. If the element’s checkedness state is true, the control represents the selected control in the group, and if it is false, it indicates a control in the group that is not selected.

The that contains an input element a also contains all the other input elements b that fulfill all of the following conditions:

• The input element b ‘s type attribute is in the Radio Button state.
• Either a and b have the same form owner, or they both have no form owner.
• Both a and b are in the same home subtree.
• They both have a name attribute, their name attributes are not empty, and the value of a ‘s name attribute is a compatibility caseless match for the value of b ‘s name attribute.

A document must not contain an input element whose radio button group contains only that element.

When any of the following phenomena occur, if the element’s checkedness state is true after the occurrence, the checkedness state of all the other elements in the same radio button group must be set to false:

• The element’s checkedness state is set to true (for whatever reason).
• The element’s name attribute is set, changed, or removed.
• The element’s form owner changes.

If the element is mutable, then: The pre-click activation steps consist of setting the element’s checkedness to true. The canceled activation steps consist of setting the element’s checkedness to false. The activation behavior is to fire a simple event that bubbles named input at the element and then fire a simple event that bubbles named change at the element. .

If the element is not mutable, it has no activation behavior.

Constraint validation: If an element in the radio button group is required, and all of the input elements in the radio button group have a checkedness that is false, then the element is suffering from being missing.

If none of the radio buttons in a radio button group are checked when they are inserted into the document, then they will all be initially unchecked in the interface, until such time as one of them is checked (either by the user or by script).

The following common input element content attributes and IDL attributes apply to the element: checked and required content attributes; checked and value IDL attributes.

The value IDL attribute is in mode default/on.

4.10.5.1.14 state ( type=file )

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

The input element represents a list of , each file consisting of a file name, a file type, and a file body (the contents of the file).

File names must not contain path components, even in the case that a user has selected an entire directory hierarchy or multiple files with the same name from different directories.

Unless the multiple attribute is set, there must be no more than one file in the list of selected files.

If the element is mutable, then the element’s activation behavior is to run the following steps:

Optionally, wait until any prior execution of this algorithm has terminated.

Display a prompt to the user requesting that the user specify some files. If the multiple attribute is not set, there must be no more than one file selected; otherwise, any number may be selected. Files can be from the filesystem or created on the fly, e.g. a picture taken from a camera connected to the user’s device.

If the element is mutable, the user agent should allow the user to change the files on the list in other ways also, e.g. adding or removing files by drag-and-drop. When the user does so, the user agent must queue a task to first update the element’s selected files so that it represents the user’s new selection, then fire a simple event that bubbles named input at the input element, and finally fire a simple event that bubbles named change at the input element.

If the element is not mutable, it has no activation behavior and the user agent must not allow the user to change the element’s selection.

Constraint validation: If the element is required and the list of selected files is empty, then the element is suffering from being missing.

The attribute may be specified to provide user agents with a hint of what file types will be accepted.

If specified, the attribute must consist of a set of comma-separated tokens, each of which must be an ASCII case-insensitive match for one of the following:

The string audio/* Indicates that sound files are accepted. The string video/* Indicates that video files are accepted. The string image/* Indicates that image files are accepted. A valid MIME type with no parameters Indicates that files of the specified type are accepted. A string whose first character is a «.» (U+002E) character Indicates that files with the specified file extension are accepted.

The tokens must not be ASCII case-insensitive matches for any of the other tokens (i.e. duplicates are not allowed). To obtain the list of tokens from the attribute, the user agent must split the attribute value on commas.

User agents may use the value of this attribute to display a more appropriate user interface than a generic file picker. For instance, given the value image/* , a user agent could offer the user the option of using a local camera or selecting a photograph from their photo collection; given the value audio/* , a user agent could offer the user the option of recording a clip using a headset microphone.

User agents should prevent the user from selecting files that are not accepted by one (or more) of these tokens.

Authors are encouraged to specify both any MIME types and any corresponding extensions when looking for data in a specific format.

For example, consider an application that converts Microsoft Word documents to Open Document Format files. Since Microsoft Word documents are described with a wide variety of MIME types and extensions, the site can list several, as follows:

On platforms that only use file extensions to describe file types, the extensions listed here can be used to filter the allowed documents, while the MIME types can be used with the system’s type registration table (mapping MIME types to extensions used by the system), if any, to determine any other extensions to allow. Similarly, on a system that does not have file names or extensions but labels documents with MIME types internally, the MIME types can be used to pick the allowed files, while the extensions can be used if the system has an extension registration table that maps known extensions to MIME types used by the system.

Extensions tend to be ambiguous (e.g. there are an untold number of formats that use the » .dat » extension, and users can typically quite easily rename their files to have a » .doc » extension even if they are not Microsoft Word documents), and MIME types tend to be unreliable (e.g. many formats have no formally registered types, and many formats are in practice labeled using a number of different MIME types). Authors are reminded that, as usual, data received from a client should be treated with caution, as it may not be in an expected format even if the user is not hostile and the user agent fully obeyed the accept attribute’s requirements.

For historical reasons, the value IDL attribute prefixes the file name with the string » C:\fakepath\ «. Some legacy user agents actually included the full path (which was a security vulnerability). As a result of this, obtaining the file name from the value IDL attribute in a backwards-compatible way is non-trivial. The following function extracts the file name in a suitably compatible manner:

This can be used as follows:

The following common input element content attributes and IDL attributes apply to the element: accept , multiple , and required content attributes; files and value IDL attributes.

The value IDL attribute is in mode filename.

The element’s value attribute must be omitted.

4.10.5.1.15 state ( type=submit )

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

The input element represents a button that, when activated, submits the form. If the element has a value attribute, the button’s label must be the value of that attribute; otherwise, it must be an implementation-defined string that means «Submit» or some such. The element is a button, specifically a submit button.

If the element is mutable, then the element’s activation behavior is as follows: if the element has a form owner, and the element’s Document is fully active, submit the form owner from the input element; otherwise, do nothing.

If the element is not mutable, it has no activation behavior.

The formnovalidate attribute can be used to make submit buttons that do not trigger the constraint validation.

The following common input element content attributes and IDL attributes apply to the element: formaction , formenctype , formmethod , formnovalidate , and formtarget content attributes; value IDL attribute.

The value IDL attribute is in mode default.

The following content attributes must not be specified and do not apply to the element: accept , alt , autocomplete , checked , dirname , height , list , max , maxlength , min , minlength , multiple , pattern , placeholder , readonly , required , size , src , step , and width .

4.10.5.1.16 state ( type=image )

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

The input element represents either an image from which a user can select a coordinate and submit the form, or alternatively a button from which the user can submit the form. The element is a button, specifically a submit button.

The coordinate is sent to the server during form submission by sending two entries for the element, derived from the name of the control but with » .x » and » .y » appended to the name with the x and y components of the coordinate respectively.

The image is given by the attribute. The src attribute must be present, and must contain a valid non-empty URL potentially surrounded by spaces referencing a non-interactive, optionally animated, image resource that is neither paged nor scripted.

When any of the following events occur, unless the user agent cannot support images, or its support for images has been disabled, or the user agent only fetches elements on demand, or the src attribute’s value is the empty string, the user agent must resolve the value of the src attribute, relative to the element, and if that is successful, must fetch the resulting absolute URL:

• The input element’s type attribute is first set to the Image Button state (possibly when the element is first created), and the src attribute is present.
• The input element’s type attribute is changed back to the Image Button state, and the src attribute is present, and its value has changed since the last time the type attribute was in the Image Button state.
• The input element’s type attribute is in the Image Button state, and the src attribute is set or changed.

Fetching the image must delay the load event of the element’s document until the task that is queued by the networking task source once the resource has been fetched (defined below) has been run.

If the image was successfully obtained, with no network errors, and the image’s type is a supported image type, and the image is a valid image of that type, then the image is said to be . If this is true before the image is completely downloaded, each task that is queued by the networking task source while the image is being fetched must update the presentation of the image appropriately.

The user agent should apply the image sniffing rules to determine the type of the image, with the image’s associated Content-Type headers giving the official type . If these rules are not applied, then the type of the image must be the type given by the image’s associated Content-Type headers.

User agents must not support non-image resources with the input element. User agents must not run executable code embedded in the image resource. User agents must only display the first page of a multipage resource. User agents must not allow the resource to act in an interactive fashion, but should honor any animation in the resource.

The task that is queued by the networking task source once the resource has been fetched, must, if the download was successful and the image is available, queue a task to fire a simple event named load at the input element; and otherwise, if the fetching process fails without a response from the remote server, or completes but the image is not a valid or supported image, queue a task to fire a simple event named error on the input element.

The attribute provides the textual label for the button for users and user agents who cannot use the image. The alt attribute must be present, and must contain a non-empty string giving the label that would be appropriate for an equivalent button if the image was unavailable.

If the src attribute is set, and the image is available and the user agent is configured to display that image, then: The element represents a control for selecting a coordinate from the image specified by the src attribute; if the element is mutable, the user agent should allow the user to select this coordinate, and the element’s activation behavior is as follows: if the element has a form owner, and the element’s Document is fully active, take the user’s selected coordinate, and submit the input element’s form owner from the input element. If the user activates the control without explicitly selecting a coordinate, then the coordinate (0,0) must be assumed.

Otherwise, the element represents a submit button whose label is given by the value of the alt attribute; if the element is mutable, then the element’s activation behavior is as follows: if the element has a form owner, and the element’s Document is fully active, set the selected coordinate to (0,0), and submit the input element’s form owner from the input element.

In either case, if the element is mutable but has no form owner or the element’s Document is not fully active, then its activation behavior must be to do nothing. If the element is not mutable, it has no activation behavior.

The must consist of an x -component and a y -component. The coordinates represent the position relative to the edge of the image, with the coordinate space having the positive x direction to the right, and the positive y direction downwards.

The x -component must be a valid integer representing a number x in the range −( border_left + padding_left ) ≤ x ≤ width + border_right + padding_right , where width is the rendered width of the image, border_left is the width of the border on the left of the image, padding_left is the width of the padding on the left of the image, border_right is the width of the border on the right of the image, and padding_right is the width of the padding on the right of the image, with all dimensions given in CSS pixels.

The y -component must be a valid integer representing a number y in the range −( border_top + padding_top ) ≤ y ≤ height + border_bottom + padding_bottom , where height is the rendered height of the image, border_top is the width of the border above the image, padding_top is the width of the padding above the image, border_bottom is the width of the border below the image, and padding_bottom is the width of the padding below the image, with all dimensions given in CSS pixels.

Where a border or padding is missing, its width is zero CSS pixels.

image . width [ = value ] image . height [ = value ]

These attributes return the actual rendered dimensions of the image, or zero if the dimensions are not known.

They can be set, to change the corresponding content attributes.

The following common input element content attributes and IDL attributes apply to the element: alt , formaction , formenctype , formmethod , formnovalidate , formtarget , height , src , and width content attributes; value IDL attribute.

The value IDL attribute is in mode default.

The following content attributes must not be specified and do not apply to the element: accept , autocomplete , checked , dirname , list , max , maxlength , min , minlength , multiple , pattern , placeholder , readonly , required , size , and step .

The element’s value attribute must be omitted.

Many aspects of this state’s behavior are similar to the behavior of the img element. Readers are encouraged to read that section, where many of the same requirements are described in more detail.

Take the following form:

If the user clicked on the image at coordinate (127,40) then the URL used to submit the form would be » process.cgi?where.x=127&where.y=40 «.

(In this example, it’s assumed that for users who don’t see the map, and who instead just see a button labeled «Show location list», clicking the button will cause the server to show a list of locations to pick from instead of the map.)

4.10.5.1.17 state ( type=reset )

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

The input element represents a button that, when activated, resets the form. If the element has a value attribute, the button’s label must be the value of that attribute; otherwise, it must be an implementation-defined string that means «Reset» or some such. The element is a button.

If the element is mutable, then the element’s activation behavior, if the element has a form owner and the element’s Document is fully active, is to reset the form owner; otherwise, it is to do nothing.

If the element is not mutable, it has no activation behavior.

Constraint validation: The element is barred from constraint validation.

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

4.10.5.1.18 state ( type=button )

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

The input element represents a button with no default behavior. A label for the button must be provided in the value attribute, though it may be the empty string. If the element has a value attribute, the button’s label must be the value of that attribute; otherwise, it must be the empty string. The element is a button.

If the element is mutable, the element’s activation behavior is to do nothing.

If the element is not mutable, it has no activation behavior.

Constraint validation: The element is barred from constraint validation.

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

4.10.5.2 Implemention notes regarding localization of form controls

This section is non-normative.

The formats shown to the user in date, time, and number controls is independent of the format used for form submission.

Browsers are encouraged to use user interfaces that present dates, times, and numbers according to the conventions of either the locale implied by the input element’s language or the user’s preferred locale. Using the page’s locale will ensure consistency with page-provided data.

For example, it would be confusing to users if an American English page claimed that a Cirque De Soleil show was going to be showing on 02/03 , but their browser, configured to use the British English locale, only showed the date 03/02 in the ticket purchase date picker. Using the page’s locale would at least ensure that the date was presented in the same format everywhere. (There’s still a risk that the user would end up arriving a month late, of course, but there’s only so much that can be done about such cultural differences. )

4.10.5.3 Common input element attributes

These attributes only apply to an input element if its type attribute is in a state whose definition declares that the attribute applies. When an attribute doesn’t apply to an input element, user agents must ignore the attribute, regardless of the requirements and definitions below.

4.10.5.3.1 The maxlength and minlength attributes

The attribute , when it applies, is a form control maxlength attribute controlled by the input element’s dirty value flag .

The attribute , when it applies, is a form control minlength attribute controlled by the input element’s dirty value flag .

If the input element has a maximum allowed value length, then the code-unit length of the value of the element’s value attribute must be equal to or less than the element’s maximum allowed value length.

The following extract shows how a messaging client’s text entry could be arbitrarily restricted to a fixed number of characters, thus forcing any conversation through this medium to be terse and discouraging intelligent discourse.

Here, a password is given a minimum length:

4.10.5.3.2 The size attribute

The attribute gives the number of characters that, in a visual rendering, the user agent is to allow the user to see while editing the element’s value.

The size attribute, if specified, must have a value that is a valid non-negative integer greater than zero.

If the attribute is present, then its value must be parsed using the rules for parsing non-negative integers, and if the result is a number greater than zero, then the user agent should ensure that at least that many characters are visible.

The size IDL attribute is limited to only non-negative numbers greater than zero and has a default value of 20.

4.10.5.3.3 The readonly attribute

The attribute is a boolean attribute that controls whether or not the user can edit the form control. When specified, the element is not mutable.

Constraint validation: If the readonly attribute is specified on an input element, the element is barred from constraint validation.

The difference between disabled and readonly is that read-only controls are still focusable, so the user can still select the text and interact with it, whereas disabled controls are entirely non-interactive. (For this reason, only text controls can be made read-only: it wouldn’t make sense for checkboxes or buttons, for instances.)

In the following example, the existing product identifiers cannot be modified, but they are still displayed as part of the form, for consistency with the row representing a new product (where the identifier is not yet filled in).

4.10.5.3.4 The required attribute

The attribute is a boolean attribute. When specified, the element is .

Constraint validation: If the element is required, and its value IDL attribute applies and is in the mode value, and the element is mutable, and the element’s value is the empty string, then the element is suffering from being missing.

The following form has two required fields, one for an e-mail address and one for a password. It also has a third field that is only considered valid if the user types the same password in the password field and this third field.

For radio buttons, the required attribute is satisfied if any of the radio buttons in the group is selected. Thus, in the following example, any of the radio buttons can be checked, not just the one marked as required:

To avoid confusion as to whether a radio button group is required or not, authors are encouraged to specify the attribute on all the radio buttons in a group. Indeed, in general, authors are encouraged to avoid having radio button groups that do not have any initially checked controls in the first place, as this is a state that the user cannot return to, and is therefore generally considered a poor user interface.

4.10.5.3.5 The multiple attribute

The attribute is a boolean attribute that indicates whether the user is to be allowed to specify more than one value.

The following extract shows how an e-mail client’s «Cc» field could accept multiple e-mail addresses.

If the user had, amongst many friends in his user contacts database, two friends «Arthur Dent» (with address «art@example.net») and «Adam Josh» (with address «adamjosh@example.net»), then, after the user has typed «a», the user agent might suggest these two e-mail addresses to the user.

The page could also link in the user’s contacts database from the site:

Suppose the user had entered «bob@example.net» into this text field, and then started typing a second e-mail address starting with «a». The user agent might show both the two friends mentioned earlier, as well as the «astrophy» and «astronomy» values given in the datalist element.

The following extract shows how an e-mail client’s «Attachments» field could accept multiple files for upload.

4.10.5.3.6 The pattern attribute

The attribute specifies a regular expression against which the control’s value, or, when the multiple attribute applies and is set, the control’s values, are to be checked.

If specified, the attribute’s value must match the JavaScript Pattern production. [ECMA262]

If an input element has a pattern attribute specified, and the attribute’s value, when compiled as a JavaScript regular expression with the global , ignoreCase , and multiline flags disabled (see ECMA262 Edition 5, sections 15.10.7.2 through 15.10.7.4), compiles successfully, then the resulting regular expression is the element’s . If the element has no such attribute, or if the value doesn’t compile successfully, then the element has no compiled pattern regular expression. [ECMA262]

Constraint validation: If the element’s value is not the empty string, and either the element’s multiple attribute is not specified or it does not apply to the input element given its type attribute’s current state, and the element has a compiled pattern regular expression but that regular expression does not match the entirety of the element’s value, then the element is suffering from a pattern mismatch.

Constraint validation: If the element’s value is not the empty string, and the element’s multiple attribute is specified and applies to the input element, and the element has a compiled pattern regular expression but that regular expression does not match the entirety of each of the element’s values, then the element is suffering from a pattern mismatch.

The compiled pattern regular expression, when matched against a string, must have its start anchored to the start of the string and its end anchored to the end of the string.

This implies that the regular expression language used for this attribute is the same as that used in JavaScript, except that the pattern attribute is matched against the entire value, not just any subset (somewhat as if it implied a ^(?: at the start of the pattern and a )$ at the end).

When an input element has a pattern attribute specified, authors should provide a description of the pattern in text near the control. Authors may also include a title attribute to give a description of the pattern. User agents may use the contents of this attribute, if it is present, when informing the user that the pattern is not matched, or at any other suitable time, such as in a tooltip or read out by assistive technology when the control gains focus.

Relying on the title attribute alone is currently discouraged as many user agents do not expose the attribute in an accessible manner as required by this specification (e.g. requiring a pointing device such as a mouse to cause a tooltip to appear, which excludes keyboard-only users and touch-only users, such as anyone with a modern phone or tablet).

For example, the following snippet includes the pattern description in text below the input , the pattern description is also included in the title attribute:

The presence of the pattern description in text makes the advice available to any user regardless of device.

The presence of the pattern description in the title attribute, results in the description being announced by assistive technology such as screen readers when the input receives focus.

If the user has attempted to submit the form with incorrect information, the presence of the title attribute text could also cause the UA to display an alert such as:

In this example, the pattern description is in text below the input , but not in the title attribute. The aria-describedby attribute is used to explicitly associate the text description with the control, the description is announced by assistive technology such as screen readers when the input receives focus:

When a control has a pattern attribute, the title attribute, if used, must describe the pattern. Additional information could also be included, so long as it assists the user in filling in the control. Otherwise, assistive technology would be impaired.

For instance, if the title attribute contained the caption of the control, assistive technology could end up saying something like The text you have entered does not match the required pattern. Birthday , which is not useful.

UAs may still show the title in non-error situations (for example, as a tooltip when hovering over the control), so authors should be careful not to word title s as if an error has necessarily occurred.

4.10.5.3.7 The min and max attributes

Some form controls can have explicit constraints applied limiting the allowed range of values that the user can provide. Normally, such a range would be linear and continuous. A form control can , however, in which case the form control’s broadest possible range is finite, and authors can specify explicit ranges within it that span the boundaries.

Specifically, the broadest range of a type=time control is midnight to midnight (24 hours), and authors can set both continuous linear ranges (such as 9pm to 11pm) and discontinuous ranges spanning midnight (such as 11pm to 1am).

The and attributes indicate the allowed range of values for the element.

Their syntax is defined by the section that defines the type attribute’s current state.

If the element has a min attribute, and the result of applying the algorithm to convert a string to a number to the value of the min attribute is a number, then that number is the element’s ; otherwise, if the type attribute’s current state defines a , then that is the minimum; otherwise, the element has no minimum.

The min attribute also defines the step base.

If the element has a max attribute, and the result of applying the algorithm to convert a string to a number to the value of the max attribute is a number, then that number is the element’s ; otherwise, if the type attribute’s current state defines a , then that is the maximum; otherwise, the element has no maximum.

If the element does not have a periodic domain, the max attribute’s value (the maximum) must not be less than the min attribute’s value (its minimum).

If an element that does not have a periodic domain has a maximum that is less than its minimum, then so long as the element has a value, it will either be suffering from an underflow or suffering from an overflow.

An element if it has a periodic domain and its maximum is less than its minimum.

An element if it has a defined minimum or a defined maximum.

Constraint validation: When the element has a minimum and does not have a reversed range, and the result of applying the algorithm to convert a string to a number to the string given by the element’s value is a number, and the number obtained from that algorithm is less than the minimum, the element is suffering from an underflow.

Constraint validation: When the element has a maximum and does not have a reversed range, and the result of applying the algorithm to convert a string to a number to the string given by the element’s value is a number, and the number obtained from that algorithm is more than the maximum, the element is suffering from an overflow.

Constraint validation: When an element has a reversed range, and the result of applying the algorithm to convert a string to a number to the string given by the element’s value is a number, and the number obtained from that algorithm is more than the maximum and less than the minimum, the element is simultaneously suffering from an underflow and suffering from an overflow.

The following date control limits input to dates that are before the 1980s:

The following number control limits input to whole numbers greater than zero:

The following time control limits input to those minutes that occur between 9pm and 6am, defaulting to midnight:

4.10.5.3.8 The step attribute

The attribute indicates the granularity that is expected (and required) of the value, by limiting the allowed values. The section that defines the type attribute’s current state also defines the , the , and in some cases the , which are used in processing the attribute as described below.

The step attribute, if specified, must either have a value that is a valid floating-point number that parses to a number that is greater than zero, or must have a value that is an ASCII case-insensitive match for the string » any «.

The attribute provides the for the element, as follows:

1. If the attribute is absent, then the allowed value step is the default step multiplied by the step scale factor.
2. Otherwise, if the attribute’s value is an ASCII case-insensitive match for the string » any «, then there is no allowed value step.
3. Otherwise, if the rules for parsing floating-point number values, when they are applied to the attribute’s value, return an error, zero, or a number less than zero, then the allowed value step is the default step multiplied by the step scale factor.
4. Otherwise, the allowed value step is the number returned by the rules for parsing floating-point number values when they are applied to the attribute’s value, multiplied by the step scale factor.

The is the value returned by the following algorithm:

If a default step base is defined for this element given its type attribute’s state, then return it and abort these steps.

Constraint validation: When the element has an allowed value step, and the result of applying the algorithm to convert a string to a number to the string given by the element’s value is a number, and that number subtracted from the step base is not an integral multiple of the allowed value step, the element is suffering from a step mismatch.

The following range control only accepts values in the range 0..1, and allows 256 steps in that range:

The following control allows any time in the day to be selected, with any accuracy (e.g. thousandth-of-a-second accuracy or more):

Normally, time controls are limited to an accuracy of one minute.

4.10.5.3.9 The list attribute

The attribute is used to identify an element that lists predefined options suggested to the user.

If present, its value must be the ID of a datalist element in the same document.

The is the first element in the document in tree order to have an ID equal to the value of the list attribute, if that element is a datalist element. If there is no list attribute, or if there is no element with that ID, or if the first element with that ID is not a datalist element, then there is no suggestions source element.

If there is a suggestions source element, then, when the user agent is allowing the user to edit the input element’s value, the user agent should offer the suggestions represented by the suggestions source element to the user in a manner suitable for the type of control used. The user agent may use the suggestion’s label to identify the suggestion if appropriate.

How user selections of suggestions are handled depends on whether the element is a control accepting a single value only, or whether it accepts multiple values:

If the element does not have a multiple attribute specified or if the multiple attribute does not apply

When the user selects a suggestion, the input element’s value must be set to the selected suggestion’s value, as if the user had written that value himself.

If the element does have a multiple attribute specified, and the multiple attribute does apply

When the user selects a suggestion, the user agent must either add a new entry to the input element’s values, whose value is the selected suggestion’s value, or change an existing entry in the input element’s values to have the value given by the selected suggestion’s value, as if the user had himself added an entry with that value, or edited an existing entry to be that value. Which behavior is to be applied depends on the user interface in a user-agent-defined manner.

This URL field offers some suggestions.

Other URLs from the user’s history might show also; this is up to the user agent.

This example demonstrates how to design a form that uses the autocompletion list feature while still degrading usefully in legacy user agents.

If the autocompletion list is merely an aid, and is not important to the content, then simply using a datalist element with children option elements is enough. To prevent the values from being rendered in legacy user agents, they need to be placed inside the value attribute instead of inline.

However, if the values need to be shown in legacy UAs, then fallback content can be placed inside the datalist element, as follows:

The fallback content will only be shown in UAs that don’t support datalist . The options, on the other hand, will be detected by all UAs, even though they are not children of the datalist element.

Note that if an option element used in a datalist is selected , it will be selected by default by legacy UAs (because it affects the select ), but it will not have any effect on the input element in UAs that support datalist .

4.10.5.3.10 The placeholder attribute

The attribute represents a short hint (a word or short phrase) intended to aid the user with data entry when the control has no value. A hint could be a sample value or a brief description of the expected format. The attribute, if specified, must have a value that contains no «LF» (U+000A) or «CR» (U+000D) characters.

The placeholder attribute should not be used as a replacement for a label . For a longer hint or other advisory text, place the text next to the control.

Use of the placeholder attribute as a replacement for a label can reduce the accessibility and usability of the control for a range of users including older users and users with cognitive, mobility, fine motor skill or vision impairments. While the hint given by the control’s label is shown at all times, the short hint given in the placeholder attribute is only shown before the user enters a value. Furthermore, placeholder text may be mistaken for a pre-filled value, and as commonly implemented the default color of the placeholder text provides insufficient contrast and the lack of a separate visible label reduces the size of the hit region available for setting focus on the control.

User agents should present this hint to the user, after having stripped line breaks from it, when the element’s value is the empty string and the control is not focused (i.e., by displaying it inside a blank unfocused control).

Here is an example of a mail configuration user interface that uses the placeholder attribute:

In situations where the control’s content has one directionality but the placeholder needs to have a different directionality, Unicode’s bidirectional-algorithm formatting characters can be used in the attribute value:

For slightly more clarity, here’s the same example using numeric character references instead of inline Arabic:

4.10.5.4 Common input element APIs

Returns the current value of the form control.

Can be set, to change the value.

Throws an InvalidStateError exception if it is set to any value other than the empty string when the control is a file upload control.

Returns the current checkedness of the form control.

Can be set, to change the checkedness.

Returns a FileList object listing the selected files of the form control.

Returns null if the control isn’t a file control.

File or Blob instances.

Returns a Date object representing the form control’s value, if applicable; otherwise, returns null.

Can be set, to change the value.

Throws an InvalidStateError exception if the control isn’t date- or time-based.

Returns a number representing the form control’s value, if applicable; otherwise, returns NaN.

Can be set, to change the value. Setting this to NaN will set the underlying value to the empty string.

Throws an InvalidStateError exception if the control is neither date- or time-based nor numeric.

input . stepUp ( [ n ] ) input . stepDown ( [ n ] )

Changes the form control’s value by the value given in the step attribute, multiplied by n . The default value for n is 1.

Throws InvalidStateError exception if the control is neither date- or time-based nor numeric, or if the step attribute’s value is » any «.

Returns the datalist element indicated by the list attribute.

The IDL attribute allows scripts to manipulate the value of an input element. The attribute is in one of the following modes, which define its behavior:

On getting, it must return the current value of the element. On setting, it must set the element’s value to the new value, set the element’s dirty value flag to true, invoke the value sanitization algorithm, if the element’s type attribute’s current state defines one, and then, if the element has a text entry cursor position, should move the text entry cursor position to the end of the text field, unselecting any selected text and resetting the selection direction to none.

On getting, if the element has a value attribute, it must return that attribute’s value; otherwise, it must return the empty string. On setting, it must set the element’s value attribute to the new value.

On getting, if the element has a value attribute, it must return that attribute’s value; otherwise, it must return the string » on «. On setting, it must set the element’s value attribute to the new value.

On getting, it must return the string » C:\fakepath\ » followed by the name of the first file in the list of selected files, if any, or the empty string if the list is empty. On setting, if the new value is the empty string, it must empty the list of selected files; otherwise, it must throw an InvalidStateError exception.

This «fakepath» requirement is a sad accident of history. See the example in the File Upload state section for more information.

The IDL attribute allows scripts to manipulate the checkedness of an input element. On getting, it must return the current checkedness of the element; and on setting, it must set the element’s checkedness to the new value and set the element’s dirty checkedness flag to true.

The IDL attribute allows scripts to access the element’s selected files. On getting, if the IDL attribute applies, it must return a FileList object that represents the current selected files. The same object must be returned until the list of selected files changes. If the IDL attribute does not apply, then it must instead return null. [FILEAPI]

The IDL attribute represents the value of the element, interpreted as a date.

On getting, if the valueAsDate attribute does not apply, as defined for the input element’s type attribute’s current state, then return null. Otherwise, run the algorithm to convert a string to a Date object defined for that state; if the algorithm returned a Date object, then return it, otherwise, return null.

On setting, if the valueAsDate attribute does not apply, as defined for the input element’s type attribute’s current state, then throw an InvalidStateError exception; otherwise, if the new value is null or a Date object representing the NaN time value, then set the value of the element to the empty string; otherwise, run the algorithm to convert a Date object to a string, as defined for that state, on the new value, and set the value of the element to the resulting string.

The IDL attribute represents the value of the element, interpreted as a number.

On getting, if the valueAsNumber attribute does not apply, as defined for the input element’s type attribute’s current state, then return a Not-a-Number (NaN) value. Otherwise, if the valueAsDate attribute applies, run the algorithm to convert a string to a Date object defined for that state; if the algorithm returned a Date object, then return the time value of the object (the number of milliseconds from midnight UTC the morning of 1970-01-01 to the time represented by the Date object), otherwise, return a Not-a-Number (NaN) value. Otherwise, run the algorithm to convert a string to a number defined for that state; if the algorithm returned a number, then return it, otherwise, return a Not-a-Number (NaN) value.

On setting, if the new value is infinite, then throw a TypeError exception. Otherwise, if the valueAsNumber attribute does not apply, as defined for the input element’s type attribute’s current state, then throw an InvalidStateError exception. Otherwise, if the new value is a Not-a-Number (NaN) value, then set the value of the element to the empty string. Otherwise, if the valueAsDate attribute applies, run the algorithm to convert a Date object to a string defined for that state, passing it a Date object whose time value is the new value, and set the value of the element to the resulting string. Otherwise, run the algorithm to convert a number to a string, as defined for that state, on the new value, and set the value of the element to the resulting string.

The and methods, when invoked, must run the following algorithm:

If the element has a minimum and a maximum and the minimum is greater than the maximum, then abort these steps.

If the element has a minimum and a maximum and there is no value greater than or equal to the element’s minimum and less than or equal to the element’s maximum that, when subtracted from the step base, is an integral multiple of the allowed value step, then abort these steps.

If value subtracted from the step base is not an integral multiple of the allowed value step, then set value to the nearest value that, when subtracted from the step base, is an integral multiple of the allowed value step, and that is less than value if the method invoked was the stepDown() and more than value otherwise.

Otherwise ( value subtracted from the step base is an integral multiple of the allowed value step), run the following substeps:

The IDL attribute must return the current suggestions source element, if any, or null otherwise.

4.10.5.5 Common event behaviors

When the input and change events apply (which is the case for all input controls other than buttons and those with the type attribute in the Hidden state), the events are fired to indicate that the user has interacted with the control. The event fires whenever the user has modified the data of the control. The event fires when the value is committed, if that makes sense for the control, or else when the control loses focus. In all cases, the input event comes before the corresponding change event (if any).

When an input element has a defined activation behavior, the rules for dispatching these events, if they apply, are given in the section above that defines the type attribute’s state. (This is the case for all input controls with the type attribute in the Checkbox state, the Radio Button state, or the File Upload state.)

For input elements without a defined activation behavior, but to which these events apply, and for which the user interface involves both interactive manipulation and an explicit commit action, then when the user changes the element’s value, the user agent must queue a task to fire a simple event that bubbles named input at the input element, and any time the user commits the change, the user agent must queue a task to fire a simple event that bubbles named change at the input element.

An example of a user interface involving both interactive manipulation and a commit action would be a Range controls that use a slider, when manipulated using a pointing device. While the user is dragging the control’s knob, input events would fire whenever the position changed, whereas the change event would only fire when the user let go of the knob, committing to a specific value.

For input elements without a defined activation behavior, but to which these events apply, and for which the user interface involves an explicit commit action but no intermediate manipulation, then any time the user commits a change to the element’s value, the user agent must queue a task to first fire a simple event that bubbles named input at the input element, and then fire a simple event that bubbles named change at the input element.

An example of a user interface with a commit action would be a Color control that consists of a single button that brings up a color wheel: if the value only changes when the dialog is closed, then that would be the explicit commit action. On the other hand, if the control can be focused and manipulating the control changes the color interactively, then there might be no commit action.

Another example of a user interface with a commit action would be a Date control that allows both text-based user input and user selection from a drop-down calendar: while text input might not have an explicit commit step, selecting a date from the drop down calendar and then dismissing the drop down would be a commit action.

For input elements without a defined activation behavior, but to which these events apply, any time the user causes the element’s value to change without an explicit commit action, the user agent must queue a task to fire a simple event that bubbles named input at the input element. The corresponding change event, if any, will be fired when the control loses focus.

Examples of a user changing the element’s value would include the user typing into a text field, pasting a new value into the field, or undoing an edit in that field. Some user interactions do not cause changes to the value, e.g. hitting the «delete» key in an empty text field, or replacing some text in the field with text from the clipboard that happens to be exactly the same text.

A Range control in the form of a slider that the user has focused and is interacting with using a keyboard would be another example of the user changing the element’s value without a commit step.

In the case of tasks that just fire an input event, user agents may wait for a suitable break in the user’s interaction before queuing the tasks; for example, a user agent could wait for the user to have not hit a key for 100ms, so as to only fire the event when the user pauses, instead of continuously for each keystroke.

When the user agent is to change an input element’s value on behalf of the user (e.g. as part of a form prefilling feature), the user agent must queue a task to first update the value accordingly, then fire a simple event that bubbles named input at the input element, then fire a simple event that bubbles named change at the input element.

These events are not fired in response to changes made to the values of form controls by scripts. (This is to make it easier to update the values of form controls in response to the user manipulating the controls, without having to then filter out the script’s own changes to avoid an infinite loop.)

4.10.6 The element

The button element represents a button labeled by its contents.

The element is a button.

The attribute controls the behavior of the button when it is activated. It is an enumerated attribute. The following table lists the keywords and states for the attribute — the keywords in the left column map to the states in the cell in the second column on the same row as the keyword.

The missing value default is the Submit Button state.

If the type attribute is in the Submit Button state, the element is specifically a submit button.

Constraint validation: If the type attribute is in the Reset Button state, or the Button state, the element is barred from constraint validation.

When a button element is not disabled, its activation behavior element is to run the steps defined in the following list for the current state of the element’s type attribute:

If the element has a form owner and the element’s Document is fully active, the element must submit the form owner from the button element.

If the element has a form owner and the element’s Document is fully active, the element must reset the form owner.

The form attribute is used to explicitly associate the button element with its form owner. The name attribute represents the element’s name. The disabled attribute is used to make the control non-interactive and to prevent its value from being submitted. The autofocus attribute controls focus. The formaction , formenctype , formmethod , formnovalidate , and formtarget attributes are attributes for form submission.

The formnovalidate attribute can be used to make submit buttons that do not trigger the constraint validation.

The formaction , formenctype , formmethod , formnovalidate , and formtarget must not be specified if the element’s type attribute is not in the Submit Button state.

The attribute gives the element’s value for the purposes of form submission. The element’s value is the value of the element’s value attribute, if there is one, or the empty string otherwise.

A button (and its value) is only included in the form submission if the button itself was used to initiate the form submission.

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

The willValidate , validity , and validationMessage IDL attributes, and the checkValidity() , and setCustomValidity() methods, are part of the constraint validation API. The labels IDL attribute provides a list of the element’s label s. The autofocus , disabled , form , and name IDL attributes are part of the element’s forms API.

The following button is labeled «Show hint» and pops up a dialog box when activated:

4.10.7 The element

The select element represents a control for selecting amongst a set of options.

The attribute is a boolean attribute. If the attribute is present, then the select element represents a control for selecting zero or more options from the list of options. If the attribute is absent, then the select element represents a control for selecting a single option from the list of options.

The attribute gives the number of options to show to the user. The size attribute, if specified, must have a value that is a valid non-negative integer greater than zero.

The of a select element is the result of applying the rules for parsing non-negative integers to the value of element’s size attribute, if it has one and parsing it is successful. If applying those rules to the attribute’s value is not successful, or if the size attribute is absent, then the element’s display size is 4 if the element’s multiple content attribute is present, and 1 otherwise.

The for a select element consists of all the option element children of the select element, and all the option element children of all the optgroup element children of the select element, in tree order.

The attribute is a boolean attribute. When specified, the user will be required to select a value before submitting the form.

If a select element has a required attribute specified, does not have a multiple attribute specified, and has a display size of 1; and if the value of the first option element in the select element’s list of options (if any) is the empty string, and that option element’s parent node is the select element (and not an optgroup element), then that option is the select element’s .

If a select element has a required attribute specified, does not have a multiple attribute specified, and has a display size of 1, then the select element must have a placeholder label option.

Constraint validation: If the element has its required attribute specified, and either none of the option elements in the select element’s list of options have their selectedness set to true, or the only option element in the select element’s list of options with its selectedness set to true is the placeholder label option, then the element is suffering from being missing.

If the multiple attribute is absent, and the element is not disabled, then the user agent should allow the user to pick an option element in its list of options that is itself not disabled. Upon this option element being (either through a click, or through unfocusing the element after changing its value, or through any other mechanism), and before the relevant user interaction event is queued (e.g. before the click event), the user agent must set the selectedness of the picked option element to true, set its dirtiness to true, and then send select update notifications.

If the multiple attribute is absent, whenever an option element in the select element’s list of options has its selectedness set to true, and whenever an option element with its selectedness set to true is added to the select element’s list of options, the user agent must set the selectedness of all the other option elements in its list of options to false.

If the multiple attribute is absent and the element’s display size is greater than 1, then the user agent should also allow the user to request that the option whose selectedness is true, if any, be unselected. Upon this request being conveyed to the user agent, and before the relevant user interaction event is queued (e.g. before the click event), the user agent must set the selectedness of that option element to false, set its dirtiness to true, and then send select update notifications.

If nodes are inserted or nodes are removed causing the list of options to gain or lose one or more option elements, or if an option element in the list of options , then, if the select element’s multiple attribute is absent, the select element’s display size is 1, and no option elements in the select element’s list of options have their selectedness set to true, the user agent must set the selectedness of the first option element in the list of options in tree order that is not disabled, if any, to true.

If the multiple attribute is present, and the element is not disabled, then the user agent should allow the user to the selectedness of the option elements in its list of options that are themselves not disabled. Upon such an element being toggled (either through a click, or any other mechanism), and before the relevant user interaction event is queued (e.g. before a related click event), the selectedness of the option element must be changed (from true to false or false to true), the dirtiness of the element must be set to true, and the user agent must send select update notifications.

When the user agent is to , queue a task to first fire a simple event that bubbles named input at the select element, and then fire a simple event that bubbles named change at the select element, using the user interaction task source as the task source.

The reset algorithm for select elements is to go through all the option elements in the element’s list of options, set their selectedness to true if the option element has a selected attribute, and false otherwise, set their dirtiness to false, and then have the option elements ask for a reset.

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

A select element that is not disabled is mutable.

Returns » select-multiple » if the element has a multiple attribute, and » select-one » otherwise.

Returns the number of elements in the list of options.

When set to a smaller number, truncates the number of option elements in the select .

When set to a greater number, adds new blank option elements to the select .

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

Returns the item with index index from the list of options. The items are sorted in tree order.

element = select . namedItem ( name )

Returns the first item with ID or name name from the list of options.

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

select . add ( element [, before ])

Inserts element before the node given by before .

The before argument can be a number, in which case element is inserted before the item with that number, or an element from the list of options, in which case element is inserted before that element.

If before is omitted, null, or a number out of range, then element will be added at the end of the list.

This method will throw a HierarchyRequestError exception if element is an ancestor of the element into which it is to be inserted.

Returns an HTMLCollection of the list of options that are selected.

Returns the index of the first selected item, if any, or −1 if there is no selected item.

Can be set, to change the selection.

Returns the value of the first selected item, if any, or the empty string if there is no selected item.

Can be set, to change the selection.

The IDL attribute, on getting, must return the string » select-one » if the multiple attribute is absent, and the string » select-multiple » if the multiple attribute is present.

The IDL attribute must return an HTMLOptionsCollection rooted at the select node, whose filter matches the elements in the list of options.

The options collection is also mirrored on the HTMLSelectElement object. The supported property indices at any instant are the indices supported by the object returned by the options attribute at that instant.

The IDL attribute must return the number of nodes represented by the options collection. On setting, it must act like the attribute of the same name on the options collection.

The method must return the value returned by the method of the same name on the options collection, when invoked with the same argument.

The method must return the value returned by the method of the same name on the options collection, when invoked with the same argument.

When the user agent is to for a given property index index to a new value value , it must instead set the value of a new indexed property with the given property index index to the new value value on the options collection.

Similarly, the method must act like its namesake method on that same options collection.

The method must act like its namesake method on that same options collection when it has arguments, and like its namesake method on the ChildNode interface implemented by the HTMLSelectElement ancestor interface Element when it has no arguments.

The IDL attribute must return an HTMLCollection rooted at the select node, whose filter matches the elements in the list of options that have their selectedness set to true.

The IDL attribute, on getting, must return the index of the first option element in the list of options in tree order that has its selectedness set to true, if any. If there isn’t one, then it must return −1.

On setting, the selectedIndex attribute must set the selectedness of all the option elements in the list of options to false, and then the option element in the list of options whose index is the given new value, if any, must have its selectedness set to true and its dirtiness set to true.

This can result in no element having a selectedness set to true even in the case of the select element having no multiple attribute and a display size of 1.

The IDL attribute, on getting, must return the value of the first option element in the list of options in tree order that has its selectedness set to true, if any. If there isn’t one, then it must return the empty string.

On setting, the value attribute must set the selectedness of all the option elements in the list of options to false, and then the first option element in the list of options, in tree order, whose value is equal to the given new value, if any, must have its selectedness set to true and its dirtiness set to true.

This can result in no element having a selectedness set to true even in the case of the select element having no multiple attribute and a display size of 1.

The , , and IDL attributes must reflect the respective content attributes of the same name. The size IDL attribute has a default value of zero.

For historical reasons, the default value of the size IDL attribute does not return the actual size used, which, in the absence of the size content attribute, is either 1 or 4 depending on the presence of the multiple attribute.

The willValidate , validity , and validationMessage IDL attributes, and the checkValidity() , and setCustomValidity() methods, are part of the constraint validation API. The labels IDL attribute provides a list of the element’s label s. The autofocus , disabled , form , and name IDL attributes are part of the element’s forms API.

The following example shows how a select element can be used to offer the user with a set of options from which the user can select a single option. The default option is preselected.

When there is no default option, a placeholder can be used instead:

Here, the user is offered a set of options from which he can select any number. By default, all five options are selected.

Sometimes, a user has to select one or more items. This example shows such an interface.

4.10.8 The element

The datalist element represents a set of option elements that represent predefined options for other controls. In the rendering, the datalist element represents nothing and it, along with its children, should be hidden .

The datalist element can be used in two ways. In the simplest case, the datalist element has just option element children.

In the more elaborate case, the datalist element can be given contents that are to be displayed for down-level clients that don’t support datalist . In this case, the option elements are provided inside a select element inside the datalist element.

The datalist element is hooked up to an input element using the list attribute on the input element.

Each option element that is a descendant of the datalist element, that is not disabled, and whose value is a string that isn’t the empty string, represents a suggestion. Each suggestion has a value and a label. datalist . options

Returns an HTMLCollection of the options elements of the datalist element.

The IDL attribute must return an HTMLCollection rooted at the datalist node, whose filter matches option elements.

Constraint validation: If an element has a datalist element ancestor, it is barred from constraint validation.

4.10.9 The element

The optgroup element represents a group of option elements with a common label.

The element’s group of option elements consists of the option elements that are children of the optgroup element.

When showing option elements in select elements, user agents should show the option elements of such groups as being related to each other and separate from other option elements.

The attribute is a boolean attribute and can be used to disable a group of option elements together.

The attribute must be specified. Its value gives the name of the group, for the purposes of the user interface. User agents should use this attribute’s value when labeling the group of option elements in a select element.

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

The following snippet shows how a set of lessons from three courses could be offered in a select drop-down widget:

4.10.10 The element

The option element represents an option in a select element or as part of a list of suggestions in a datalist element.

In certain circumstances described in the definition of the select element, an option element can be a select element’s placeholder label option. A placeholder label option does not represent an actual option, but instead represents a label for the select control.

The attribute is a boolean attribute. An option element is if its disabled attribute is present or if it is a child of an optgroup element whose disabled attribute is present.

An option element that is disabled must prevent any click events that are queued on the user interaction task source from being dispatched on the element.

The attribute provides a label for element. The of an option element is the value of the label content attribute, if there is one, or, if there is not, the value of the element’s text IDL attribute.

The label content attribute, if specified, must not be empty.

The attribute provides a value for element. The of an option element is the value of the value content attribute, if there is one, or, if there is not, the value of the element’s text IDL attribute.

The attribute is a boolean attribute. It represents the default selectedness of the element.

The of an option element is a boolean state, initially false. It controls whether adding or removing the selected content attribute has any effect.

The of an option element is a boolean state, initially false. Except where otherwise specified, when the element is created, its selectedness must be set to true if the element has a selected attribute. Whenever an option element’s selected attribute is added, if its dirtiness is false, its selectedness must be set to true. Whenever an option element’s selected attribute is removed, if its dirtiness is false, its selectedness must be set to false.

The Option() constructor, when called with three or fewer arguments, overrides the initial state of the selectedness state to always be false even if the third argument is true (implying that a selected attribute is to be set). The fourth argument can be used to explicitly set the initial selectedness state when using the constructor.

A select element whose multiple attribute is not specified must not have more than one descendant option element with its selected attribute set.

An option element’s is the number of option elements that are in the same list of options but that come before it in tree order. If the option element is not in a list of options, then the option element’s index is zero.

Returns true if the element is selected, and false otherwise.

Can be set, to override the current state of the element.

Returns the index of the element in its select element’s options list.

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

Same as textContent , except that spaces are collapsed and script elements are skipped.

option = new Option ( [ text [, value [, defaultSelected [, selected ] ] ] ] )

Returns a new option element.

The text argument sets the contents of the element.

The value argument sets the value attribute.

The defaultSelected argument sets the selected attribute.

The selected argument sets whether or not the element is selected. If it is omitted, even if the defaultSelected argument is true, the element is not selected.

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

The IDL attribute, on getting, must return the element’s label. On setting, the element’s label content attribute must be set to the new value.

The IDL attribute, on getting, must return the element’s value. On setting, the element’s value content attribute must be set to the new value.

The IDL attribute, on getting, must return true if the element’s selectedness is true, and false otherwise. On setting, it must set the element’s selectedness to the new value, set its dirtiness to true, and then cause the element to ask for a reset.

The IDL attribute must return the element’s index.

The IDL attribute, on getting, must return the result of stripping and collapsing whitespace from the concatenation of data of all the Text node descendants of the option element, in tree order, excluding any that are descendants of descendants of the option element that are themselves script elements in the HTML namespace or script elements in the SVG namespace.

On setting, the text attribute must act as if the textContent IDL attribute on the element had been set to the new value.

The IDL attribute’s behavior depends on whether the option element is in a select element or not. If the option has a select element as its parent, or has an optgroup element as its parent and that optgroup element has a select element as its parent, then the form IDL attribute must return the same value as the form IDL attribute on that select element. Otherwise, it must return null.

A constructor is provided for creating HTMLOptionElement objects (in addition to the factory methods from DOM such as createElement() ): . When invoked as a constructor, it must return a new HTMLOptionElement object (a new option element). If the first argument is not the empty string, the new object must have as its only child a Text node whose data is the value of that argument. Otherwise, it must have no children. If the value argument is present, the new object must have a value attribute set with the value of the argument as its value. If the defaultSelected argument is true, the new object must have a selected attribute set with no value. If the selected argument is true, the new object must have its selectedness set to true; otherwise the selectedness must be set to false, even if the defaultSelected argument is true. The element’s document must be the active document of the browsing context of the Window object on which the interface object of the invoked constructor is found.

4.10.11 The element

The textarea element represents a multiline plain text edit control for the element’s . The contents of the control represent the control’s default value.

The raw value of a textarea control must be initially the empty string.

The attribute is a boolean attribute used to control whether the text can be edited by the user or not.

In this example, a text field is marked read-only because it represents a read-only file:

Constraint validation: If the readonly attribute is specified on a textarea element, the element is barred from constraint validation.

A textarea element is mutable if it is neither disabled nor has a readonly attribute specified.

When a textarea is mutable, its raw value should be editable by the user: the user agent should allow the user to edit, insert, and remove text, and to insert and remove line breaks in the form of «LF» (U+000A) characters. Any time the user causes the element’s raw value to change, the user agent must queue a task to fire a simple event that bubbles named input at the textarea element. User agents may wait for a suitable break in the user’s interaction before queuing the task; for example, a user agent could wait for the user to have not hit a key for 100ms, so as to only fire the event when the user pauses, instead of continuously for each keystroke.

A textarea element has a , which must be initially set to false, and must be set to true whenever the user interacts with the control in a way that changes the raw value.

When the textarea element’s textContent IDL attribute changes value, if the element’s dirty value flag is false, then the element’s raw value must be set to the value of the element’s textContent IDL attribute.

The reset algorithm for textarea elements is to set the element’s value to the value of the element’s textContent IDL attribute.

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:

The attribute specifies the expected maximum number of characters per line. If the cols attribute is specified, its value must be a valid non-negative integer greater than zero. If applying the rules for parsing non-negative integers to the attribute’s value results in a number greater than zero, then the element’s is that value; otherwise, it is 20.

The user agent may use the textarea element’s character width as a hint to the user as to how many characters the server prefers per line (e.g. for visual user agents by making the width of the control be that many characters). In visual renderings, the user agent should wrap the user’s input in the rendering so that each line is no wider than this number of characters.

The attribute specifies the number of lines to show. If the rows attribute is specified, its value must be a valid non-negative integer greater than zero. If applying the rules for parsing non-negative integers to the attribute’s value results in a number greater than zero, then the element’s is that value; otherwise, it is 2.

Visual user agents should set the height of the control to the number of lines given by character height.

The attribute is an enumerated attribute with two keywords and states: the keyword which maps to the Soft state, and the keyword which maps to the Hard state. The missing value default is the Soft state.

The state indicates that the text in the textarea is not to be wrapped when it is submitted (though it can still be wrapped in the rendering).

The state indicates that the text in the textarea is to have newlines added by the user agent so that the text is wrapped when it is submitted.

If the element’s wrap attribute is in the Hard state, the cols attribute must be specified.

For historical reasons, the element’s value is normalised in three different ways for three different purposes. The raw value is the value as it was originally set. It is not normalized. The API value is the value used in the value IDL attribute. It is normalized so that line breaks use «LF» (U+000A) characters. Finally, there is the form submission value. It is normalized so that line breaks use U+000D CARRIAGE RETURN «CRLF» (U+000A) character pairs, and in addition, if necessary given the element’s wrap attribute, additional line breaks are inserted to wrap the text at the given width.

The element’s is defined to be the element’s raw value with the following transformation applied:

The element’s value is defined to be the element’s raw value with the following transformation applied:

If the textarea element has a maximum allowed value length, then the element’s children must be such that the code-unit length of the value of the element’s textContent IDL attribute is equal to or less than the element’s maximum allowed value length.

The attribute is a boolean attribute. When specified, the user will be required to enter a value before submitting the form.

Constraint validation: If the element has its required attribute specified, and the element is mutable, and the element’s value is the empty string, then the element is suffering from being missing.

The attribute represents a short hint (a word or short phrase) intended to aid the user with data entry when the control has no value. A hint could be a sample value or a brief description of the expected format.

The placeholder attribute should not be used as a replacement for a label . For a longer hint or other advisory text, place the text next to the control.

Use of the placeholder attribute as a replacement for a label can reduce the accessibility and usability of the control for a range of users including older users and users with cognitive, mobility, fine motor skill or vision impairments. While the hint given by the control’s label is shown at all times, the short hint given in the placeholder attribute is only shown before the user enters a value. Furthermore, placeholder text may be mistaken for a pre-filled value, and as commonly implemented the default color of the placeholder text provides insufficient contrast and the lack of a separate visible label reduces the size of the hit region available for setting focus on the control.

User agents should present this hint to the user when the element’s value is the empty string and the control is not focused (e.g. by displaying it inside a blank unfocused control). All U+000D CARRIAGE RETURN U+000A LINE FEED character pairs (CRLF) in the hint, as well as all other «CR» (U+000D) and «LF» (U+000A) characters in the hint, must be treated as line breaks when rendering the hint.

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 textarea element with its form owner. The autofocus attribute controls focus. The autocomplete attribute controls how the user agent provides autofill behavior.

Returns the string » textarea «.

Returns the current value of the element.

Can be set, to change the value.

The , , , , and attributes must reflect the respective content attributes of the same name. The cols and rows attributes are limited to only non-negative numbers greater than zero. The cols attribute’s default value is 20. The rows attribute’s default value is 2. The IDL attribute must reflect the dirname content attribute. The IDL attribute must reflect the maxlength content attribute, limited to only non-negative numbers. The IDL attribute must reflect the minlength content attribute, limited to only non-negative numbers. The IDL attribute must reflect the readonly content attribute.

The IDL attribute must return the value » textarea «.

The IDL attribute must act like the element’s textContent IDL attribute.

The attribute must, on getting, return the element’s API value; on setting, it must set the element’s raw value to the new value, set the element’s dirty value flag to true, and should then move the text entry cursor position to the end of the text field, unselecting any selected text and resetting the selection direction to none.

The IDL attribute must return the code-unit length of the element’s API value.

The willValidate , validity , and validationMessage IDL attributes, and the checkValidity() , and setCustomValidity() methods, are part of the constraint validation API. The labels IDL attribute provides a list of the element’s label s. 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.

Here is an example of a textarea being used for unrestricted free-form text input in a form:

To specify a maximum length for the comments, one can use the maxlength attribute:

To give a default value, text can be included inside the element:

You can also give a minimum length. Here, a letter needs to be filled out by the user; a template (which is shorter than the minimum length) is provided, but is insufficient to submit the form:

A placeholder can be given as well, to suggest the basic form to the user, without providing an explicit template:

To have the browser submit the directionality of the element along with the value, the dirname attribute can be specified:

4.10.12 The element

The keygen element represents a key pair generator control. When the control’s form is submitted, the private key is stored in the local keystore, and the public key is packaged and sent to the server.

The attribute may be specified. Its value will be packaged with the submitted key.

The attribute is an enumerated attribute. The following table lists the keywords and states for the attribute — the keywords in the left column map to the states listed in the cell in the second column on the same row as the keyword. User agents are not required to support these values, and must only recognize values whose corresponding algorithms they support.

The invalid value default state is the unknown state. The missing value default state is the RSA state, if it is supported, or the unknown state otherwise.

This specification does not specify what key types user agents are to support — it is possible for a user agent to not support any key types at all.

The user agent may expose a user interface for each keygen element to allow the user to configure settings of the element’s key pair generator, e.g. the key length.

The reset algorithm for keygen elements is to set these various configuration settings back to their defaults.

The element’s value is the string returned from the following algorithm:

Use the appropriate step from the following list:

If the keytype attribute is in the EC state

. http://www.mail-archive.com/dev-tech-crypto@lists.mozilla.org/msg05902.html —> If the keytype attribute is in the RSA state

Generate an RSA key pair using the settings given by the user, if appropriate, using the md5WithRSAEncryption RSA signature algorithm (the signature algorithm with MD5 and the RSA encryption algorithm) referenced in section 2.2.1 («RSA Signature Algorithm») of RFC 3279, and defined in RFC 3447. [RFC3279] [RFC3447]

Otherwise, the keytype attribute is in the unknown state

The given key type is not supported. Return the empty string and abort this algorithm.

Let private key be the generated private key.

Let public key be the generated public key.

Let signature algorithm be the selected signature algorithm.

If the element has a challenge attribute, then let challenge be that attribute’s value. Otherwise, let challenge be the empty string.

Let algorithm be an ASN.1 AlgorithmIdentifier structure as defined by RFC 5280, with the algorithm field giving the ASN.1 OID used to identify signature algorithm , using the OIDs defined in section 2.2 («Signature Algorithms») of RFC 3279, and the parameters field set up as required by RFC 3279 for AlgorithmIdentifier structures for that algorithm. [X690] [RFC5280] [RFC3279]

Let spki be an ASN.1 SubjectPublicKeyInfo structure as defined by RFC 5280, with the algorithm field set to the algorithm structure from the previous step, and the subjectPublicKey field set to the BIT STRING value resulting from ASN.1 DER encoding the public key . [X690] [RFC5280]

Let publicKeyAndChallenge be an ASN.1 PublicKeyAndChallenge structure as defined below, with the spki field set to the spki structure from the previous step, and the challenge field set to the string challenge obtained earlier. [X690]

Let signature be the BIT STRING value resulting from ASN.1 DER encoding the signature generated by applying the signature algorithm to the byte string obtained by ASN.1 DER encoding the publicKeyAndChallenge structure, using private key as the signing key. [X690]

Let signedPublicKeyAndChallenge be an ASN.1 SignedPublicKeyAndChallenge structure as defined below, with the publicKeyAndChallenge field set to the publicKeyAndChallenge structure, the signatureAlgorithm field set to the algorithm structure, and the signature field set to the BIT STRING signature from the previous step. [X690]

Return the result of base64 encoding the result of ASN.1 DER encoding the signedPublicKeyAndChallenge structure. [RFC4648] [X690]

The data objects used by the above algorithm are defined as follows. These definitions use the same «ASN.1-like» syntax defined by RFC 5280. [RFC5280]

Constraint validation: The keygen element is barred from constraint validation.

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

Returns the string » keygen «.

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

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

The IDL attribute must return the value » keygen «.

The willValidate , validity , and validationMessage IDL attributes, and the checkValidity() , and setCustomValidity() methods, are part of the constraint validation API. The labels IDL attribute provides a list of the element’s label s. The autofocus , disabled , form , and name IDL attributes are part of the element’s forms API.

This specification does not specify how the private key generated is to be used. It is expected that after receiving the SignedPublicKeyAndChallenge (SPKAC) structure, the server will generate a client certificate and offer it back to the user for download; this certificate, once downloaded and stored in the key store along with the private key, can then be used to authenticate to services that use TLS and certificate authentication.

and turned it into a client cert? —>

To generate a key pair, add the private key to the user’s key store, and submit the public key to the server, markup such as the following can be used:

The server will then receive a form submission with a packaged RSA public key as the value of » key «. This can then be used for various purposes, such as generating a client certificate, as mentioned above.

4.10.13 The element

The output element represents the result of a calculation or user action.

The content attribute allows an explicit relationship to be made between the result of a calculation and the elements that represent the values that went into the calculation or that otherwise influenced the calculation. The for attribute, if specified, must contain a string consisting of an unordered set of unique space-separated tokens that are case-sensitive, each of which must have the value of an ID of an element in the same Document .

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

The element has a which is either value or default. Initially, the value mode flag must be set to default.

The element also has a . Initially, the default value must be the empty string.

When the value mode flag is in mode default, the contents of the element represent both the value of the element and its default value. When the value mode flag is in mode value, the contents of the element represent the value of the element only, and the default value is only accessible using the defaultValue IDL attribute.

Whenever the element’s descendants are changed in any way, if the value mode flag is in mode default, the element’s default value must be set to the value of the element’s textContent IDL attribute.

The reset algorithm for output elements is to set the element’s value mode flag to default and then to set the element’s textContent IDL attribute to the value of the element’s default value (thus replacing the element’s child nodes).

Returns the element’s current value.

Can be set, to change the value.

Returns the element’s current default value.

Can be set, to change the default value.

Returns the string » output «.

The IDL attribute must act like the element’s textContent IDL attribute, except that on setting, in addition, before the child nodes are changed, the element’s value mode flag must be set to value.

The IDL attribute, on getting, must return the element’s default value. On setting, the attribute must set the element’s default value, and, if the element’s value mode flag is in the mode default, set the element’s textContent IDL attribute as well.

The attribute must return the string » output «.

The IDL attribute must reflect the for content attribute.

The willValidate , validity , and validationMessage IDL attributes, and the checkValidity() , and setCustomValidity() methods, are part of the constraint validation API. The labels IDL attribute provides a list of the element’s label s. The form and name IDL attributes are part of the element’s forms API.

A simple calculator could use output for its display of calculated results:

In this example, an output element is used to report the results from a remote server, as they come in:

4.10.14 The element

The progress element represents the completion progress of a task. The progress is either indeterminate, indicating that progress is being made but that it is not clear how much more work remains to be done before the task is complete (e.g. because the task is waiting for a remote host to respond), or the progress is a number in the range zero to a maximum, giving the fraction of work that has so far been completed.

There are two attributes that determine the current task completion represented by the element. The attribute specifies how much of the task has been completed, and the attribute specifies how much work the task requires in total. The units are arbitrary and not specified.

To make a determinate progress bar, add a value attribute with the current progress (either a number from 0.0 to 1.0, or, if the max attribute is specified, a number from 0 to the value of the max attribute). To make an indeterminate progress bar, remove the value attribute.

Authors are encouraged to also include the current value and the maximum value inline as text inside the element, so that the progress is made available to users of legacy user agents.

Here is a snippet of a Web application that shows the progress of some automated task:

(The updateProgress() method in this example would be called by some other code on the page to update the actual progress bar as the task progressed.)

The value and max attributes, when present, must have values that are valid floating-point numbers. The value attribute, if present, must have a value equal to or greater than zero, and less than or equal to the value of the max attribute, if present, or 1.0, otherwise. The max attribute, if present, must have a value greater than zero.

The progress element is the wrong element to use for something that is just a gauge, as opposed to task progress. For instance, indicating disk space usage using progress would be inappropriate. Instead, the meter element is available for such use cases.

User agent requirements: If the value attribute is omitted, then the progress bar is an indeterminate progress bar. Otherwise, it is a determinate progress bar.

If the progress bar is a determinate progress bar and the element has a max attribute, the user agent must parse the max attribute’s value according to the rules for parsing floating-point number values. If this does not result in an error, and if the parsed value is greater than zero, then the of the progress bar is that value. Otherwise, if the element has no max attribute, or if it has one but parsing it resulted in an error, or if the parsed value was less than or equal to zero, then the maximum value of the progress bar is 1.0.

If the progress bar is a determinate progress bar, user agents must parse the value attribute’s value according to the rules for parsing floating-point number values. If this does not result in an error, and if the parsed value is less than the maximum value and greater than zero, then the of the progress bar is that parsed value. Otherwise, if the parsed value was greater than or equal to the maximum value, then the current value of the progress bar is the maximum value of the progress bar. Otherwise, if parsing the value attribute’s value resulted in an error, or a number less than or equal to zero, then the current value of the progress bar is zero.

UA requirements for showing the progress bar: When representing a progress element to the user, the UA should indicate whether it is a determinate or indeterminate progress bar, and in the former case, should indicate the relative position of the current value relative to the maximum value.

For a determinate progress bar (one with known current and maximum values), returns the result of dividing the current value by the maximum value.

For an indeterminate progress bar, returns −1.

If the progress bar is an indeterminate progress bar, then the IDL attribute must return −1. Otherwise, it must return the result of dividing the current value by the maximum value.

If the progress bar is an indeterminate progress bar, then the IDL attribute, on getting, must return 0. Otherwise, it must return the current value. On setting, the given value must be converted to the best representation of the number as a floating-point number and then the value content attribute must be set to that string.

Setting the value IDL attribute to itself when the corresponding content attribute is absent would change the progress bar from an indeterminate progress bar to a determinate progress bar with no progress.

The IDL attribute must reflect the content attribute of the same name, limited to numbers greater than zero. The default value for max is 1.0.

The labels IDL attribute provides a list of the element’s label s.

4.10.15 The element

The meter element represents a scalar measurement within a known range, or a fractional value; for example disk usage, the relevance of a query result, or the fraction of a voting population to have selected a particular candidate.

This is also known as a gauge.

The meter element should not be used to indicate progress (as in a progress bar). For that role, HTML provides a separate progress element.

The meter element also does not represent a scalar value of arbitrary range — for example, it would be wrong to use this to report a weight, or height, unless there is a known maximum value.

There are six attributes that determine the semantics of the gauge represented by the element.

The attribute specifies the lower bound of the range, and the attribute specifies the upper bound. The attribute specifies the value to have the gauge indicate as the «measured» value.

The other three attributes can be used to segment the gauge’s range into «low», «medium», and «high» parts, and to indicate which part of the gauge is the «optimum» part. The attribute specifies the range that is considered to be the «low» part, and the attribute specifies the range that is considered to be the «high» part. The attribute gives the position that is «optimum»; if that is higher than the «high» value then this indicates that the higher the value, the better; if it’s lower than the «low» mark then it indicates that lower values are better, and naturally if it is in between then it indicates that neither high nor low values are good.

Authoring requirements: The value attribute must be specified. The value , min , low , high , max , and optimum attributes, when present, must have values that are valid floating-point numbers.

In addition, the attributes’ values are further constrained:

Let value be the value attribute’s number.

If the min attribute is specified, then let minimum be that attribute’s value; otherwise, let it be zero.

If the max attribute is specified, then let maximum be that attribute’s value; otherwise, let it be 1.0.

The following inequalities must hold, as applicable:

• minimum ≤ value ≤ maximum
• minimum ≤ low ≤ maximum (if low is specified)
• minimum ≤ high ≤ maximum (if high is specified)
• minimum ≤ optimum ≤ maximum (if optimum is specified)
• low ≤ high (if both low and high are specified)

If no minimum or maximum is specified, then the range is assumed to be 0..1, and the value thus has to be within that range.

Authors are encouraged to include a textual representation of the gauge’s state in the element’s contents, for users of user agents that do not support the meter element.

The following examples show three gauges that would all be three-quarters full:

The following example is incorrect use of the element, because it doesn’t give a range (and since the default maximum is 1, both of the gauges would end up looking maxed out):

Instead, one would either not include the meter element, or use the meter element with a defined range to give the dimensions in context compared to other pies:

There is no explicit way to specify units in the meter element, but the units may be specified in the title attribute in free-form text.

The example above could be extended to mention the units:

User agent requirements: User agents must parse the min , max , value , low , high , and optimum attributes using the rules for parsing floating-point number values.

User agents must then use all these numbers to obtain values for six points on the gauge, as follows. (The order in which these are evaluated is important, as some of the values refer to earlier ones.)

If the min attribute is specified and a value could be parsed out of it, then the minimum value is that value. Otherwise, the minimum value is zero.

If the max attribute is specified and a value could be parsed out of it, then the candidate maximum value is that value. Otherwise, the candidate maximum value is 1.0.

If the candidate maximum value is greater than or equal to the minimum value, then the maximum value is the candidate maximum value. Otherwise, the maximum value is the same as the minimum value.

If the value attribute is specified and a value could be parsed out of it, then that value is the candidate actual value. Otherwise, the candidate actual value is zero.

If the candidate actual value is less than the minimum value, then the actual value is the minimum value.

Otherwise, if the candidate actual value is greater than the maximum value, then the actual value is the maximum value.

Otherwise, the actual value is the candidate actual value.

If the low attribute is specified and a value could be parsed out of it, then the candidate low boundary is that value. Otherwise, the candidate low boundary is the same as the minimum value.

If the candidate low boundary is less than the minimum value, then the low boundary is the minimum value.

Otherwise, if the candidate low boundary is greater than the maximum value, then the low boundary is the maximum value.

Otherwise, the low boundary is the candidate low boundary.

If the high attribute is specified and a value could be parsed out of it, then the candidate high boundary is that value. Otherwise, the candidate high boundary is the same as the maximum value.

If the candidate high boundary is less than the low boundary, then the high boundary is the low boundary.

Otherwise, if the candidate high boundary is greater than the maximum value, then the high boundary is the maximum value.

Otherwise, the high boundary is the candidate high boundary.

If the optimum attribute is specified and a value could be parsed out of it, then the candidate optimum point is that value. Otherwise, the candidate optimum point is the midpoint between the minimum value and the maximum value.

If the candidate optimum point is less than the minimum value, then the optimum point is the minimum value.

Otherwise, if the candidate optimum point is greater than the maximum value, then the optimum point is the maximum value.

Otherwise, the optimum point is the candidate optimum point.

All of which will result in the following inequalities all being true:

• minimum value ≤ actual value ≤ maximum value
• minimum value ≤ low boundary ≤ high boundary ≤ maximum value
• minimum value ≤ optimum point ≤ maximum value

UA requirements for regions of the gauge: If the optimum point is equal to the low boundary or the high boundary, or anywhere in between them, then the region between the low and high boundaries of the gauge must be treated as the optimum region, and the low and high parts, if any, must be treated as suboptimal. Otherwise, if the optimum point is less than the low boundary, then the region between the minimum value and the low boundary must be treated as the optimum region, the region from the low boundary up to the high boundary must be treated as a suboptimal region, and the remaining region must be treated as an even less good region. Finally, if the optimum point is higher than the high boundary, then the situation is reversed; the region between the high boundary and the maximum value must be treated as the optimum region, the region from the high boundary down to the low boundary must be treated as a suboptimal region, and the remaining region must be treated as an even less good region.

UA requirements for showing the gauge: When representing a meter element to the user, the UA should indicate the relative position of the actual value to the minimum and maximum values, and the relationship between the actual value and the three regions of the gauge.

The following markup:

Might be rendered as follows:

User agents may combine the value of the title attribute and the other attributes to provide context-sensitive help or inline text detailing the actual values.

For example, the following snippet:

. might cause the user agent to display a gauge with a tooltip saying «Value: 23.2 out of 60.» on one line and «seconds» on a second line.

The IDL attribute, on getting, must return the actual value. On setting, the given value must be converted to the best representation of the number as a floating-point number and then the value content attribute must be set to that string.

The IDL attribute, on getting, must return the minimum value. On setting, the given value must be converted to the best representation of the number as a floating-point number and then the min content attribute must be set to that string.

The IDL attribute, on getting, must return the maximum value. On setting, the given value must be converted to the best representation of the number as a floating-point number and then the max content attribute must be set to that string.

The IDL attribute, on getting, must return the low boundary. On setting, the given value must be converted to the best representation of the number as a floating-point number and then the low content attribute must be set to that string.

The IDL attribute, on getting, must return the high boundary. On setting, the given value must be converted to the best representation of the number as a floating-point number and then the high content attribute must be set to that string.

The IDL attribute, on getting, must return the optimum value. On setting, the given value must be converted to the best representation of the number as a floating-point number and then the optimum content attribute must be set to that string.

The labels IDL attribute provides a list of the element’s label s.

The following example shows how a gauge could fall back to localized or pretty-printed text.

4.10.16 The element

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

Returns the string «fieldset».

Returns an HTMLFormControlsCollection of the form controls in the element.

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

The IDL attribute must return the string » fieldset «.

The 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. The form and name IDL attributes are part of the element’s forms API.

This example shows a fieldset element being used to group a set of related controls:

The div elements used in the code samples above and below are not intended to convey any semantic meaning and are used only to create a non-inline rendering of the grouped fieldset controls.

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.

You can also nest fieldset elements. Here is an example expanding on the previous one that does so:

In this example, if the outer «Use Club Card» checkbox is not checked, everything inside the outer fieldset , including the two radio buttons in the legends of the two nested fieldset s, will be disabled. However, if the checkbox is checked, then the radio buttons will both be enabled and will let you select which of the two inner fieldset s is to be enabled.

4.10.17 The element

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

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

The 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.18 Form control infrastructure

4.10.18.1 A form control’s value

Form controls have a and a . (The latter is only used by input elements.) These are used to describe how the user interacts with the control.

To define the behaviour of constraint validation in the face of the input element’s multiple attribute, input elements can also have separately defined .

4.10.18.2 Mutability

A form control can be designated as .

This determines (by means of definitions and requirements in this specification that rely on whether an element is so designated) whether or not the user can modify the value or checkedness of a form control, or whether or not a control can be automatically prefilled.

4.10.18.3 Association of controls and forms

A form-associated element can have a relationship with a form element, which is called the element’s . If a form-associated element is not associated with a form element, its form owner is said to be null.

A form-associated element is, by default, associated with its nearest ancestor form element (as described below) , but, if it is reassociateable, may have a attribute specified to override this.

This feature allows authors to work around the lack of support for nested form elements.

If a reassociateable form-associated element has a form attribute specified, then that attribute’s value must be the ID of a form element in the element’s owner Document .

The rules in this section are complicated by the fact that although conforming documents will never contain nested form elements, it is quite possible (e.g. using a script that performs DOM manipulation) to generate documents that have such nested elements. They are also complicated by rules in the HTML parser that, for historical reasons, can result in a form-associated element being associated with a form element that is not its ancestor.

When a form-associated element is created, its form owner must be initialized to null (no owner).

When a form-associated element is to be with a form, its form owner must be set to that form.

When a form-associated element or one of its ancestors is inserted into a Document , then the user agent must reset the form owner of that form-associated element. The HTML parser overrides this requirement when inserting form controls.

When an element is removed from a Document resulting in a form-associated element and its form owner (if any) no longer being in the same home subtree, then the user agent must reset the form owner of that form-associated element.

When a reassociateable form-associated element’s form attribute is set, changed, or removed, then the user agent must reset the form owner of that element.

When a reassociateable form-associated element has a form attribute and the ID of any of the elements in the Document changes, then the user agent must reset the form owner of that form-associated element.

When a reassociateable form-associated element has a form attribute and an element with an ID is inserted into or removed from the Document , then the user agent must reset the form owner of that form-associated element.

When the user agent is to of a form-associated element, it must run the following steps:

If the element is reassociateable, has a form content attribute, and is itself in a Document , then run these substeps:

In the following non-conforming snippet:

The form owner of «d» would be the inner nested form «c», while the form owner of «e» would be the outer form «a».

This happens as follows: First, the «e» node gets associated with «c» in the HTML parser. Then, the innerHTML algorithm moves the nodes from the temporary document to the «b» element. At this point, the nodes see their ancestor chain change, and thus all the «magic» associations done by the parser are reset to normal ancestor associations.

This example is a non-conforming document, though, as it is a violation of the content models to nest form elements.

Returns the element’s form owner.

Returns null if there isn’t one.

Reassociateable form-associated elements have a IDL attribute, which, on getting, must return the element’s form owner, or null if there isn’t one.

4.10.19

4.10.19.1 Naming form controls: the name attribute

The content attribute gives the name of the form control, as used in form submission and in the form element’s elements object. If the attribute is specified, its value must not be the empty string.

Any non-empty value for name is allowed, but the names » _charset_ » and » isindex » are special:

This value, if used as the name of a Text control that is the first control in a form that is submitted using the application/x-www-form-urlencoded mechanism, causes the submission to only include the value of this control, with no name.

This value, if used as the name of a Hidden control with no value attribute, is automatically given a value during submission consisting of the submission character encoding.

The IDL attribute must reflect the name content attribute.

4.10.19.2 Submitting element directionality: the dirname attribute

The attribute on a form control element enables the submission of the directionality of the element, and gives the name of the field that contains this value during form submission. If such an attribute is specified, its value must not be the empty string.

In this example, a form contains a text field and a submission button:

When the user submits the form, the user agent includes three fields, one called «comment», one called «comment.dir», and one called «mode»; so if the user types «Hello», the submission body might be something like:

If the user manually switches to a right-to-left writing direction and enters » مرحبا «, the submission body might be something like:

4.10.19.3 Limiting user input length: the maxlength attribute

A , controlled by a dirty value flag , declares a limit on the number of characters a user can input.

If an element has its form control maxlength attribute specified, the attribute’s value must be a valid non-negative integer. If the attribute is specified and applying the rules for parsing non-negative integers to its value results in a number, then that number is the element’s . If the attribute is omitted or parsing its value results in an error, then there is no maximum allowed value length.

Constraint validation: If an element has a maximum allowed value length, its dirty value flag is true, its value was last changed by a user edit (as opposed to a change made by a script), and the code-unit length of the element’s value is greater than the element’s maximum allowed value length, then the element is suffering from being too long.

User agents may prevent the user from causing the element’s value to be set to a value whose code-unit length is greater than the element’s maximum allowed value length.

4.10.19.4 Setting minimum input length requirements: the minlength attribute

A , controlled by a dirty value flag , declares a lower bound on the number of characters a user can input.

The minlength attribute does not imply the required attribute. If the form control has no minlength attribute, then the value can still be omitted; the minlength attribute only kicks in once the user has entered a value at all. If the empty string is not allowed, then the required attribute also needs to be set.

If an element has its form control minlength attribute specified, the attribute’s value must be a valid non-negative integer. If the attribute is specified and applying the rules for parsing non-negative integers to its value results in a number, then that number is the element’s . If the attribute is omitted or parsing its value results in an error, then there is no minimum allowed value length.

Constraint validation: If an element has a minimum allowed value length, its value is not the empty string, and the code-unit length of the element’s value is less than the element’s minimum allowed value length, then the element is suffering from being too short.

In this example, there are four text fields. The first is required, and has to be at least 5 characters long. The other three are optional, but if the user fills one in, the user has to enter at least 10 characters.

4.10.19.5 Enabling and disabling form controls: the disabled attribute

The content attribute is a boolean attribute.

A form control is if its disabled attribute is set, or if it is a descendant of a fieldset element whose disabled attribute is set and is not a descendant of that fieldset element’s first legend element child, if any.

A form control that is disabled must prevent any click events that are queued on the user interaction task source from being dispatched on the element.

Constraint validation: If an element is disabled, it is barred from constraint validation.

The IDL attribute must reflect the disabled content attribute.

4.10.19.6 Form submission

can be specified both on form elements and on submit buttons (elements that represent buttons that submit forms, e.g. an input element whose type attribute is in the Submit Button state).

The corresponding attributes for form submission that may be specified on submit buttons are formaction , formenctype , formmethod , formnovalidate , and formtarget . When omitted, they default to the values given on the corresponding attributes on the form element.

The and content attributes, if specified, must have a value that is a valid non-empty URL potentially surrounded by spaces.

The of an element is the value of the element’s formaction attribute, if the element is a submit button and has such an attribute, or the value of its form owner’s action attribute, if it has one, or else the empty string.

The and content attributes are enumerated attributes with the following keywords and states:

• The keyword , mapping to the state , indicating the HTTP GET method.
• The keyword , mapping to the state , indicating the HTTP POST method.

The invalid value default for these attributes is the GET state. The missing value default for the method attribute is also the GET state. (There is no missing value default for the formmethod attribute.)

The of an element is one of those states. If the element is a submit button and has a formmethod attribute, then the element’s method is that attribute’s state; otherwise, it is the form owner’s method attribute’s state.

Here the method attribute is used to explicitly specify the default value, » get «, so that the search query is submitted in the URL:

On the other hand, here the method attribute is used to specify the value » post «, so that the user’s message is submitted in the HTTP request’s body:

The and content attributes are enumerated attributes with the following keywords and states:

• The «» keyword and corresponding state.
• The «» keyword and corresponding state.
• The «» keyword and corresponding state.

The invalid value default for these attributes is the application/x-www-form-urlencoded state. The missing value default for the enctype attribute is also the application/x-www-form-urlencoded state. (There is no missing value default for the formenctype attribute.)

The of an element is one of those three states. If the element is a submit button and has a formenctype attribute, then the element’s enctype is that attribute’s state; otherwise, it is the form owner’s enctype attribute’s state.

The and content attributes, if specified, must have values that are valid browsing context names or keywords.

The of an element is the value of the element’s formtarget attribute, if the element is a submit button and has such an attribute; or the value of its form owner’s target attribute, if it has such an attribute; or, if the Document contains a base element with a target attribute, then the value of the target attribute of the first such base element; or, if there is no such element, the empty string.

The and content attributes are boolean attributes. If present, they indicate that the form is not to be validated during submission.

The of an element is true if the element is a submit button and the element’s formnovalidate attribute is present, or if the element’s form owner’s novalidate attribute is present, and false otherwise.

This attribute is useful to include «save» buttons on forms that have validation constraints, to allow users to save their progress even though they haven’t fully entered the data in the form. The following example shows a simple form that has two required fields. There are three buttons: one to submit the form, which requires both fields to be filled in; one to save the form so that the user can come back and fill it in later; and one to cancel the form altogether.

The IDL attribute must reflect the content attribute of the same name, except that on getting, when the content attribute is missing or its value is the empty string, the document’s address must be returned instead. The IDL attribute must reflect the content attribute of the same name. The and IDL attributes must reflect the respective content attributes of the same name, limited to only known values. The IDL attribute must reflect the enctype content attribute, limited to only known values. The IDL attribute must reflect the novalidate content attribute. The IDL attribute must reflect the formaction content attribute, except that on getting, when the content attribute is missing or its value is the empty string, the document’s address must be returned instead. The IDL attribute must reflect the formenctype content attribute, limited to only known values. The IDL attribute must reflect the formmethod content attribute, limited to only known values. The IDL attribute must reflect the formnovalidate content attribute. The IDL attribute must reflect the formtarget content attribute.

4.10.19.7 Autofocusing a form control: the autofocus attribute

The content attribute allows the author to indicate that a control is to be focused as soon as the page is loaded, allowing the user to just start typing without having to manually focus the main control.

An element’s is the element’s root element.

There must not be two elements with the same nearest ancestor autofocus scoping root element that both have the autofocus attribute specified.

When an element with the autofocus attribute specified is inserted into a document, user agents should run the following steps:

This handles the automatic focusing during document load.

Focusing the control does not imply that the user agent must focus the browser window if it has lost focus.

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

In the following snippet, the text control would be focused when the document was loaded.

4.10.19.8 Autofilling form controls: the autocomplete attribute

User agents sometimes have features for helping users fill forms in, for example prefilling the user’s address based on earlier user input. The content attribute can be used to hint to the user agent how to, or indeed whether to, provide such a feature.

The attribute, if present, must have a value that is an ASCII case-insensitive match for the string » off «, or a single token that is an ASCII case-insensitive match for the string » on «

The «» keyword indicates either that the control’s input data is particularly sensitive (for example the activation code for a nuclear weapon); or that it is a value that will never be reused (for example a one-time-key for a bank login) and the user will therefore have to explicitly enter the data each time, instead of being able to rely on the UA to prefill the value for him; or that the document provides its own autocomplete mechanism and does not want the user agent to provide autocompletion values.

The «» keyword indicates that the user agent is allowed to provide the user with autocompletion values, but does not provide any further information about what kind of data the user might be expected to enter. User agents would have to use heuristics to decide what autocompletion values to suggest.

If the autocomplete attribute is omitted, the default value corresponding to the state of the element’s form owner’s autocomplete attribute is used instead (either » on » or » off «). If there is no form owner, then the value » on » is used.

When an element’s autofill field name is » off «, the user agent should not remember the control’s value, and should not offer past values to the user.

In addition, when an element’s autofill field name is » off «, values are reset when traversing the history.

Banks frequently do not want UAs to prefill login information:

When an element’s autofill field name is not » off «, the user agent may store the control’s value, and may offer previously stored values to the user.

When the autofill field name is » on «, the user agent should attempt to use heuristics to determine the most appropriate values to offer the user, e.g. based on the element’s name value, the position of the element in the document’s DOM, what other fields exist in the form, and so forth.

The autocompletion mechanism must be implemented by the user agent acting as if the user had modified the element’s value, and must be done at a time where the element is mutable (e.g. just after the element has been inserted into the document, or when the user agent stops parsing). User agents must only prefill controls using values that the user could have entered.

A user agent prefilling a form control’s value must not cause that control to suffer from a type mismatch, suffer from a pattern mismatch, suffer from being too long, suffer from being too short, suffer from an underflow, suffer from an overflow, or suffer from a step mismatch. Where possible given the control’s constraints, user agents must use the format given as canonical in the aforementioned table. Where it’s not possible for the canonical format to be used, user agents should use heuristics to attempt to convert values so that they can be used.

A user agent may allow the user to override an element’s autofill field name , e.g. to change it from » off » to » on » to allow values to be remembered and prefilled despite the page author’s objections, or to always » off «, never remembering values. However, user agents should not allow users to trivially override the autofill field name from » off » to » on » or other values, as there are significant security implications for the user if all values are always remembered, regardless of the site’s preferences.

The IDL attribute, on getting, must return the element’s IDL-exposed autofill value , and on setting, must reflect the content attribute of the same name.

4.10.20 APIs for the text field selections

The input and textarea elements define the following members in their DOM interfaces for handling their selection:

The setRangeText method uses the following enumeration:

These methods and attributes expose and control the selection of input and textarea text fields.

Selects everything in the text field.

element . selectionStart [ = value ]

Returns the offset to the start of the selection.

Can be set, to change the start of the selection.

element . selectionEnd [ = value ]

Returns the offset to the end of the selection.

Can be set, to change the end of the selection.

element . selectionDirection [ = value ]

Returns the current direction of the selection.

Can be set, to change the direction of the selection.

The possible values are » forward «, » backward «, and » none «.

element . setSelectionRange ( start , end [, direction ] )

Changes the selection to cover the given substring in the given direction. If the direction is omitted, it will be reset to be the platform default (none or forward).

element . setRangeText ( replacement [, start , end [, selectionMode ] ] )

Replaces a range of text with the new text. If the start and end arguments are not provided, the range is assumed to be the selection.

The final argument determines how the selection should be set after the text has been replaced. The possible values are:

» select » Selects the newly inserted text. » start » Moves the selection to just before the inserted text. » end » Moves the selection to just after the selected text. » preserve » Attempts to preserve the selection. This is the default.

For input elements, calling these methods while they don’t apply, and getting or setting these attributes while they don’t apply, must throw an InvalidStateError exception. Otherwise, they must act as described below.

For input elements, these methods and attributes must operate on the element’s value. For textarea elements, these methods and attributes must operate on the element’s raw value.

Where possible, user interface features for changing the text selection in input and textarea elements must be implemented in terms of the DOM API described in this section, so that, e.g., all the same events fire.

The selections of input and textarea elements have a direction, which is either forward, backward, or none. This direction is set when the user manipulates the selection. The exact meaning of the selection direction depends on the platform.

On Windows, the direction indicates the position of the caret relative to the selection: a forward selection has the caret at the end of the selection and a backward selection has the caret at the start of the selection. Windows has no none direction. On Mac, the direction indicates which end of the selection is affected when the user adjusts the size of the selection using the arrow keys with the Shift modifier: the forward direction means the end of the selection is modified, and the backwards direction means the start of the selection is modified. The none direction is the default on Mac, it indicates that no particular direction has yet been selected. The user sets the direction implicitly when first adjusting the selection, based on which directional arrow key was used.

The method must cause the contents of the text field to be fully selected, with the selection direction being none, if the platform support selections with the direction none, or otherwise forward. The user agent must then queue a task to fire a simple event that bubbles named select at the element, using the user interaction task source as the task source.

The attribute must, on getting, return the offset (in logical order) to the character that immediately follows the start of the selection. If there is no selection, then it must return the offset (in logical order) to the character that immediately follows the text entry cursor.

On setting, it must act as if the setSelectionRange() method had been called, with the new value as the first argument; the current value of the selectionEnd attribute as the second argument, unless the current value of the selectionEnd is less than the new value, in which case the second argument must also be the new value; and the current value of the selectionDirection as the third argument.

The attribute must, on getting, return the offset (in logical order) to the character that immediately follows the end of the selection. If there is no selection, then it must return the offset (in logical order) to the character that immediately follows the text entry cursor.

On setting, it must act as if the setSelectionRange() method had been called, with the current value of the selectionStart attribute as the first argument, the new value as the second argument, and the current value of the selectionDirection as the third argument.

The attribute must, on getting, return the string corresponding to the current selection direction: if the direction is forward, » forward «; if the direction is backward, » backward «; and otherwise, » none «.

On setting, it must act as if the setSelectionRange() method had been called, with the current value of the selectionStart attribute as the first argument, the current value of the selectionEnd attribute as the second argument, and the new value as the third argument.

The method must set the selection of the text field to the sequence of characters starting with the character at the start th position (in logical order) and ending with the character at the ( end -1) th position. Arguments greater than the length of the value of the text field must be treated as pointing at the end of the text field. If end is less than or equal to start then the start of the selection and the end of the selection must both be placed immediately before the character with offset end . In UAs where there is no concept of an empty selection, this must set the cursor to be just before the character with offset end . The direction of the selection must be set to backward if direction is a case-sensitive match for the string » backward «, forward if direction is a case-sensitive match for the string » forward » or if the platform does not support selections with the direction none, and none otherwise (including if the argument is omitted). The user agent must then queue a task to fire a simple event that bubbles named select at the element, using the user interaction task source as the task source.

The method must run the following steps:

If the method has only one argument, then let start and end have the values of the selectionStart attribute and the selectionEnd attribute respectively.

Otherwise, let start , end have the values of the second and third arguments respectively.