input (type=datetime) element

If you don't know what an element is or how you must use it, I recommend you read the "HTML tags and attributes" tutorial that you can find in the HTML tutorials section.

Description

The input element, having the "datetime" value in its type attribute, represents a field for a global date and time that gathers data with time-zone information. This type of field is particularly useful for the grathering of universal points in time, that are equivalent in any part of the world. For example, the date and time of an online meeting should be collected by this control, so it's exactly the same for all participants.

In modern browsers global date and time fields are usually represented by controls that enable users to change their value in a graphical way (like, for example, a calendar), instead of having to input it directly as a string.

Upon submission, supporting browsers convert the input data into a string representing a normalized forced-UTC global date and time (this is what the processing agent will receive server-side). The rules to compose a valid global date and time or normalized global date and time are described below.

Global dates and times

A global date and time syntax is composed by:

  1. A valid date syntax representing year, month and day.
  2. A capital letter T or a space character (" ").
  3. A valid time syntax representing the time.
  4. A valid time zone syntax representing the time-zone offset.

Example

<time>2014-01-14 00:12-03:00</time>
<time>2014-05-16T20:12+00:30</time>
<time>2201-08-20 03:04:22.5-5:00</time>
<time>2000-04-01T02:00:00.00+4:00</time>

For a global date and time syntax to be a normalised forced-UTC global date and time string, it must be composed by:

  1. A valid date syntax representing year, month and day, converted to UTC time zone.
  2. A capital letter T.
  3. A valid time syntax representing the time, converted to UTC time zone and in its shortest variant (for example, omitting the number of seconds when it's zero).
  4. A capital letter Z.

Example

<time>2014-02-03T22:00Z</time>
<time>2010-01-01T00:00:00.001Z</time>
<time>2050-01-03T23:59Z</time>
<time>1980-12-23T00:05Z</time>

Dates

A date syntax is composed by:

  1. A valid month syntax representing year and month.
  2. A minus sign or hypen character ("-").
  3. A two digits day between 1 and the numbers of days for the previously specified month and year.

Example

<time>2014-07-05</time>
<time>1920-12-31</time>

Months

A month syntax is composed by:

  1. A year greater than zero, consisting of at least four digits.
  2. A minus sign or hypen character ("-").
  3. A month between 1 and 12, consisting of two digits.

Example

<time>2014-07</time>
<time>0512-12</time>

Times

A time syntax is composed by:

  1. Two digits representing an hour between 0 and 23.
  2. A colon character (":").
  3. A two digits minute between 0 and 59.
  4. The following information, which is optional if the number of seconds is zero:
    1. A colon character (":").
    2. Two digits representing the integer part of the seconds, between 0 and 59.
    3. The following information, which is optional if the number of seconds is an integer:
      1. A period or full stop character (".").
      2. The fractional part of the seconds composed by one, two or three digits.

Example

<time>23:59:59.999</time>
<time>10:20:00.000</time>
<time>10:20</time>
<time>10:20:00</time>

Time zones

A time zone syntax is composed by:

  1. A minus sign or hypen character ("-") if the offset is negative, and a plus sign character ("-") otherwise.
  2. Two digits representing an hour between 0 and 23.
  3. Optionally, a colon character (":").
  4. A two digits minute between 0 and 59.

Example

<time>-12:00</time>
<time>+00:00</time>
<time>+00:30</time>
<time>-1100</time>

This format allows a range of time zones wider than what's currently used in practice. The reason for this excess is to improve adaptability to future time zones changes, as they are subject to political decisions.

Browser support for datetime fields is very low. To improve compatibility, authors may have to rely on scripts to provide advanced controls and to check values conformance before submission.

The min and max attributes may be used in this element to set a range of valid dates and times the user will be able to submit.

Examples

In the first example we'll only create a form with a date and time control. Here you'll be able to note the functionality provided by your browser (if any) for the control.

<form action="../../form-result.php" target="_blank">
  <p>Meeting: <input type="datetime" name="meetingtime"> <input type="submit" value="Send data"></p>
</form>

Meeting:

In our second example we'll provide a list of suggested values using the datalist element, so the user can quickliy pick up one of the predefined values when the browser suggests them. The control will be linked to the datalist because of the matching between the id attribute in the list and the list attribute in the control.

Browser support for datalist is incomplete. Authors may have to rely on scripts to provide this functionality cross-browser.

The values provided by the datalist element must conform with the requirements of global date and time strings.

<form action="../../form-result.php" method="post" target="_blank">
  <p>
    Make an appointment: <input type="datetime" name="appointmentdate" list="appointmentdateslist">
    <input type="submit" value="Send data">
  </p>
</form>
<datalist id="appointmentdateslist">
  <option value="2015-05-05 08:00Z">
  <option value="2015-05-12 11:30-03:00">
  <option value="2015-05-19 09:00+01:00">
  <option value="2015-05-26 22:19:45.32+00:00">
</datalist>

Make an appointment:

In our last example we'll be working with the attributes min, max and step to put restrictions to the values the user can input. With this configuration we're setting a minimum date, a maximum date, and the distance between a selectable date and the following (in number of seconds), respectively. Más específicamente, we'll only allow the user to pick any hour in the range, without minutes or seconds.

When the step attribute is present, authors should specify a date and time to be taken as initial step. This can be done through the attributes min and value. When both are present, the min attribute takes precedence.

The values provided in the attributes min, max and step must conform with the requirements of global date and time strings.

<form action="../../form-result.php" target="_blank">
  <p>
    Make an appointment: <input type="datetime" name="appointmentdate" min="2015-02-20 10:00Z" max="2015-04-24 10:00Z" step="3600">
    <input type="submit" value="Send data">
  </p>
</form>

Make an appointment:

Attributes

Specific attributes

autocomplete

One of two values indicating the browser if it should automatically suggest options for this control, as an attempt to guess what the user is typing. Browsers usually perform this action by retrieving data from a database containing previous inputs. There are two possible values, both case-insensitive:

  • on: the browser should suggest options automatically. This is the default value.
  • off: the browser musn't suggest options automatically.

Example

<form action="../../form-result.php" method="post" target="_blank">
  <p>
    Party starts: <input type="datetime" name="partydatetime" autocomplete="off">
    <input type="submit" value="Set">
  </p>
</form>

Party starts:

autofocus

A boolean value instructing the browser to set the focus to this control when the document has finished loading or when the dialog where the control finds itself is shown. If the attribute has the value "autofocus" or the empty string (""), or if it's just present, the control should get the focus as soon as possible, after the page or dialog has been loaded.

Example

<p>Inscriptions will be open from: <input type="datetime" name="inscriptionsopen" autofocus></p>

disabled

A boolean value indicating wether the control is disabled or not. If the attribute takes the value "disabled" or the empty string (""), or if it's just present, the control will be disabled.

Disabled controls are rendered greyed out (if visible), are blocked from user interaction and, more importantly, their values (if any) aren't sent when the form is submitted.

Example

<form action="../../form-result.php" method="post" target="_blank">
  <p>
    Meeting: <input type="datetime" name="meetingdatetime" disabled>
    <input type="submit" value="Send data">
  </p>
</form>

Meeting:

form

The value of the id attribute of the form with which this control is associated to.

This attribute is new in HTML5 and helps defining the pertenence of controls in nested or distant forms.

Example

<p>Departure: <input type="datetime" name="departuredatetime" form="form1"></p>
<form id="form1" action="../../form-result.php" method="post" target="_blank">
  <p><input type="submit" value="Send data"></p>
</form>

Departure:

list

A token matching the value of the id attribute of the datalist this control is assopciated with. The datalist referenced by this attribute will provide a number of suggestions that users can pick to autocomplete the control.

Browser support for datalist is incomplete. Authors may have to rely on scripts to provide this functionality cross-browser.

The values provided by the datalist element must conform with the requirements of global date and time strings.

Example

<form action="../../form-result.php" method="post" target="_blank">
  <p>
    Take off: <input type="datetime" name="takeoffdatetime" list="takeofflist">
    <input type="submit" value="Send data">
  </p>
</form>
<datalist id="takeofflist">
  <option value="2015-03-10 09:00Z">
  <option value="2015-03-10 10:00Z">
  <option value="2015-03-10 11:00Z">
  <option value="2015-03-10 12:00Z">
</datalist>

Take off:

max

The maximum date the user should be able to pick. Supporting browsers are supposed to disallow the selection of any date greater than the one specified in this attribute.

The value provided in this attribute must conform with the requirements of global date and time strings.

Example

<form action="../../form-result.php" method="post" target="_blank">
  <p>
    Wait until: <input type="datetime" name="waituntil" max="2015-12-31 23:59:59.999Z">
    <input type="submit" value="Send data">
  </p>
</form>

Wait until:

min

The minimum date the user should be able to pick. Supporting browsers are supposed to disallow the selection of any date less than the one specified in this attribute.

The value provided in this attribute must conform with the requirements of global date and time strings.

Example

<form action="../../form-result.php" method="post" target="_blank">
  <p>
    Born in: <input type="datetime" name="bornin" min="2003-02-10 10:00Z">
    <input type="submit" value="Send data">
  </p>
</form>

Born in:

name

A name for the control. This name will be sent by the browser to the processing agent, paired with the content of the value attribute. Both attributes together will conform a name-value pair that will be used to process the form data.

Currently, the value isindex, formerly used in a special way by some browsers and included in the HTML standard, isn't permitted in this attribute.

Example

<form action="../../form-result.php" method="post" target="_blank">
  <p>
    Date of birth: <input type="datetime" name="birth">
    <input type="submit" value="Send data">
  </p>
</form>

Date of birth:

readonly

A boolean value instructing the browser to prevent the user from changing the control's value. If this attribute has the value "readonly" or the empty string (""), or if it's just present, the user won't be allowed to change the value in the control.

Although this attribute prevents the control's value from being edited, not all interaction is blocked: users will still be able to select and copy the text in the control.

Example

<form action="../../form-result.php" method="post" target="_blank">
  <p>
    Appointment: <input type="datetime" name="appointment" value="2015-05-15 15:30+03:00" readonly>
    <input type="submit" value="Send data">
  </p>
</form>

Appointment:

required

A boolean value indicating wether this control can be left empty or not. If this attribute has the value "required" or the empty string (""), or if it's just present, the user will have to fill the control in order to be able to submit the form.

If a control with the required attribute present is left blank, supporting browsers will throw an error upon submission and cancel the process immediately.

Browser support for the attribute required is incomplete. Authors may have to rely on scripts to provide this functionality cross-browser.

Example

<form action="../../form-result.php" method="post" target="_blank">
  <p>
    Member since: <input type="datetime" name="membersince" required>
    <input type="submit" value="Send data">
  </p>
</form>

Member since:

step

A number of seconds to be used as the amount of space between an allowed value and the next one. The presence of this attribute reduces the number of choices the user will have by restricting the selection of intermediate values.

To avoid unexpected behaviors, authors should specify a date and time to be taken as initial step. This can be done through the attributes min and value. When both are present, the min attribute takes precedence.

Example

<form action="../../form-result.php" method="post" target="_blank">
  <p>
    Next session: <input type="datetime" name="nextsession" step="3600" min="2015-02-16 08:00-03:00">
    <input type="submit" value="Send data">
  </p>
</form>

Next session:

type

A value indicating the type of the field that this element represents. There are twenty two possible values (case-insensitive):

  • hidden: a hidden control used to send information to the server, typically managed by scripts.
  • text: a control used to input a single-line piece of text.
  • search: same as text but for search purposes.
  • tel: a control used to provide a telephone number.
  • url: a text box used to input a single and absolute URL.
  • email: a control designed to edit one or more e-mail addresses.
  • password: a text box for editing passwords, where the characters are represented by dots.
  • date: a control to input a specific date.
  • month: a control to input a specific month.
  • week: a control to input a specific week.
  • time: a control to input a specific time.
  • datetime-local: a control to input a specific local date and time.
  • number: a control to input a number.
  • range: a control to input one or two numbers inside a range.
  • color: a control to input a color.
  • checkbox: a control to input a boolean value (true/false).
  • radio: a control used to choose one single option among many.
  • file: a control used to upload files to the server.
  • submit: a button used to submit the form.
  • image: same as submit but with the ability to be shown as an image instead of using the default button appearance.
  • reset: a button used to reset the form's controls to their default values.
  • button: a button with no default action associated.

When this attribute isn't present, the element behaves as it would have the value "text".

Example

<input type="datetime" name="starton">

value

An initial value for the control, that will be set when the page loads and when the reset button is pressed.

The value provided in this attribute must conform with the requirements of global date and time strings.

Example

<form action="../../form-result.php" method="post" target="_blank">
  <p>Send me an alert on: <input type="datetime" name="alert" value="2015-02-21 15:35Z"></p>
  <p>
    <input type="submit" value="Send data">
    <input type="reset" value="Reset form">
  </p>
</form>

Send me an alert on:

Global attributes

For information about global attributes refer to this list of global attributes in HTML5.

Events

Global events

For information about global events refer to this list of global events in HTML5.