input

input elements allow input of different types of values into a document. They're generally used in the context of a form.

See also:

Content category

Pseudo-classes

Attributes

The type attribute sets data type and associated form control for the input:

  • hidden allows submission of an arbitrary string that is not made visible to the user. This is useful for persisting values across multi-step processes, or for submitting identifiers related with an item being edited. text allows input of a single line of text, with line breaks automatically removed from the input. For multi-line text entry, see `textarea`.
  • search behaves like text, except that it may include a clear button in the field for easy reset and may cause mobile browsers to show a search icon in the keyboard.
  • tel is an input designed for phone number input, and should cause mobile devices to show a numeric keypad.
  • url behaves like text, but has specialised navigation and may cause mobile devices to display an appropriate keyboard.
  • email lets the user input an email address using a text input with specialised validation. Depending on the browser, platform and locale it may also select a more appropriate keyboard.
  • password behaves like a text field, except that its value is masked (e.g. with * or •).
  • date allows input of a year, month and day. The input should be in the user's locale, but the output will be in ISO-8601 format (YYYY-MM-DD).
  • month lets the user input a month and year. Output is in the form YYYY-MM.
  • week allows entry of a week number and year. Output is in the form YYYY-Www.
  • time allows entry of a time with no time zone. Output is in the form HH:MM.
  • datetime-local allows the user to input a local date and time, which may not be valid in their local timezone. The input should be in the user's locale, and output may or not be a valid ISO-8601 format (YYYY-MM-DDTHH:MM) until after normalisation. It's not well supported in MobileSafari and should be avoided for now.
  • number provides a simple number input, and may cause browsers to show a numeric input. Desktop browsers may show increment and decrement buttons.
  • range allow input of a numeric value between min and max.
  • color yields a native colour picker. Depending on the browser, input may be in multiple different colour systems (RGB, HSL, hex), but the specification mandates that the output be a 7-charcter hex string (e.g .#678abc).
  • checkbox creates a checkbox which allows toggling a single boolean value.
  • radio creates an individual radio button which may be grouped with others by name.
  • file lets the user select a file for upload.
  • submit buttons submit the form.
  • image allows use of an image for an upload button.
  • reset creates a button which resets the values of all form elements to their default values. Use of this is usually an antipattern; it is not a commonly intended behaviour.
  • button creates a button with no associated behaviour.

These attributes apply to all inputs, regardless of type:

autocomplete accepts a space-delimited list of values:

  • off disables autocomplete, and should be used where there are security concerns with the
  • on enables autocomplete, but provides no hints as to how and leaves the behaviour at the browser's discretion.
  • name means the full name. Although not recommended due to broad differences in locale, it can be further broken down:
    • honorific-prefix for prefix/title.
    • given-name for the given/first name.
    • additional-name for middle names.
    • family-name for the family/last name.
    • honorific-suffix for the suffix (Jr, PhD., etc.).
    • nickname for a nickname/handle.
  • email for an email address.
  • username for a username.
  • new-password for a new password for an account. This should be used for both the password and confirmation fields.
  • current-password for the password currently in use.
  • one-time-code for one-time passwords.
  • organization-title for a job title.
  • organization for a place of work.
  • street-address for a complete street address; may be a multi-line field.
  • address-line1, address-line2 and address-line3 for individual address lines. Must not be present alongside street-address.
  • address-level4, address-level3, address-level2 and address-level1 represent administrative parts of an address, from most to least precise.
  • country for a country or territory code.
  • country-name for a country or territory name.
  • postal-code for a postal or zip code.
  • cc-name for the full name, as printed on a credit card, or alternatively:
    • cc-given-name for the given/first name.
    • cc-additional-name for the middle names.
    • cc-family-name for the family/last name.
  • cc-exp for the expiration date, typically expressed in the form MM/YY or MM/YYYY, or:
    • cc-exp-month for the expiration month.
    • cc-exp-year for the expiration year.
  • cc-csc for the CSC/CVV number, usually a three or four digit number.
  • cc-type for the type of payment instrument (e.g. Visa, MasterCard, Amex).
  • transaction-currency for the currency of the transaction.
  • transaction-amount for the amount to be billed, in the currency specified by transaction-currency.
  • language for a preferred language, as per BCP 47.
  • bday for a birth date, expressed as a full date, or:
    • bday-day for the day.
    • bday-month for the month.
    • bday-year for the year.
  • sex for gender identity.
  • tel for a complete telephone number, or:
    • tel-country-code for the international dialling code, e.g. 1 for the USA or 44 for the UK.
    • tel-national for a full number within the country, e.g. 0808 2000 247.
    • tel-area-code for the area code.
    • tel-local for a valid local phone number.
  • tel-extension for a telephone extension within the phone number (e.g. room/suite number).
  • impp for an IM protocol endpoint.
  • url for a URL.
  • photo for the URL of a photo.

  • autofocus focuses the input when it or its parent dialog are made visible.
  • disabled indicates that the control should be disabled.
  • form allows explicit association of the element with a form (using its id).
  • name specifies the name of the input control, and the name against which the value will be submitted. Without this, the value will not be included in submissions.
  • pattern specifies a regular expression that a value must match to be considered valid.
  • placeholder text is displayed to the user in the form as an example/hint of what is expected.
  • value sets the initial value of the input. Note that button types display this on the control.

The remaining attributes are based on the type attribute:

  • Unless type="hidden", type="password" or the type otherwise doesn't accept a numeric or text value:
    • list can be set to the id of a `datalist` containing predefined values to suggest to the user. This does not constrain the user to these values.
  • If type="email" or type="file":
    • multiple determines whether or not to allow multiple values.
  • If type="file":
    • accept allows specifying the expected type of a selected file in a comma-delimited list:
      • .my-extension indicates a file extension.
      • application/x-some-format indicates a MIME type.
  • If type="image":
    • src specifies the address of the referenced image.
    • alt specifies alternative text to be used if the image is unavailable.
  • If type="checkbox" or type="radio":
    • checked indicates that the input should be pre-selected.
  • If type="text" or type="search":
    • dirname indicates the name of the form field to use for submission of the field's text directionality.
  • If type="submit":
    • formaction, formenctype, formmethod, formnovalidate and formtarget override the form's corresponding elements.
  • If the type allows specification of a numeric or date/time value:
    • min sets the minimum valid value.
    • max sets the maximum valid value.
    • step indicates how much the value should increase by. For numeric types this defaults to 1, for dates it it's expressed in seconds and defaults to 60.
  • If the type allows specification of text:
    • minlength sets the minimum length of the value (in UTF-16 code units).
    • maxlength sets the maximum length of the value (in UTF-16 code units).
  • If the input allows free entry of text:
    • readonly behaves similarly to disabled, but the input's value will still be submitted along with the form.
    • required determines whether an empty value will pass validation.

References


Backlinks