Description Provides a widget to select dates. The date picker can render as an overlay relative to input fields, or as a static calendar widget.
Required Script <script async custom-element="amp-date-picker" src="https://cdn.ampproject.org/v0/amp-date-picker-0.1.js"></script>
Supported Layouts
  • For static mode: fixed, fixed-height, responsive, fill or flex-item
  • For overlay mode: container
Examples See AMP By Example's amp-date-picker.

Behavior

You can use the amp-date-picker to render a calendar on a page that a user can select dates from.

Example: Basic calendar

In this example, we display a fixed-height static calendar, where a user can select a single date:

<amp-date-picker
  layout="fixed-height"
  height="360">
</amp-date-picker>

Example: Calendar for a specific input field

In this example, the calendar displays as an overlay for the specific form field:

<form
  method="post"
  action-xhr="/form/echo-json/post"
  target="_blank">
  <amp-date-picker
      mode="overlay"
      layout="container"
      input-selector="[name=deliverydate]">
    <label for="deliverydate">Deliver Date:</label>
    <input type="text" name="deliverydate">
  </amp-date-picker>
</form>

Display modes

The amp-date-picker provides two modes to render the date picker: static (default) or overlay.

Static mode

By specifying mode="static", the amp-date-picker renders a static calendar view. This is the default display mode; if no mode is specified, a static calendar is rendered.

For a static date picker, you must specify a size-defined layout, which can be one of: fixed, fixed-height, responsive, fill or flex-item.

When the static amp-date-picker is rendered in a <form>, if there are no inputs specified with *input-selector, the amp-date-picker creates hidden input elements (e.g., <input type="hidden" ...). The amp-date-picker names the elements as date or start-date and end-date; if those names are already used in the form, the amp-date-picker attempts to name the input fields with the id of the <amp-date-picker>.

Example: static date picker in a form field

This example demonstrates using a static date picker in a form, where the user can select a date range in the calendar. As there are no *input-selector attributes defined in the amp-date-picker, hidden input fields are automatically generated.

<form
  method="post"
  action-xhr="/form-post"
  target="_blank">
<fieldset>
  <label>
    <span>Your name</span>
    <input type="text" name="name" id="name" required>
  </label>
  <label for="date">Your date</label>
  <amp-date-picker
      type="range"
      mode="static"
      id="date"
      layout="fixed-height"
      height="360">
    <!-- automatically generates hidden input fields:
    <input type="hidden" name="start-date">
    <input type="hidden" name="end-date"> -->
  </amp-date-picker>
  <input type="submit" value="Subscribe">
</fieldset>
<div submit-success>
<template type="amp-mustache">
  Success! Thanks {{name}} for choosing {{start-date}} and {{end-date}}.
</template>
</div>
</form>

Overlay mode

By specifying mode="overlay", when the user clicks, focuses, or presses the down-arrow in an input field connected with the amp-date-picker, the calendar appears. The calendar overlay positions itself relative to the <amp-date-picker> tag.

For an overlay date picker, you must specify layout="container" and contain the input fields that it will render.

Example: overlay date picker in a form

This example demonstrates using a overlay date picker in a form where the user can choose a date. The date picker is connected to a specific input field via the input-selector attribute.

<form
  method="post"
  action-xhr="/form-post"
  target="_blank">
  <input type="text" name="name" placeholder="Your Name" required>
  <amp-date-picker
      type="single"
      mode="overlay"
      layout="container"
      input-selector="[name=date]">
    <input type="text" name="date" placeholder="Your Date">
  </amp-date-picker>
  <input type="submit" value="Subscribe">
  <div submit-success>
    <template type="amp-mustache">
      Success! Thanks {{name}} for choosing {{date}}.
    </template>
  </div>
  </form>

Selection types

The amp-date-picker provides two types of dates to select:

  • single: Select a single date within the date picker.
  • range: Select a date range within the date picker.

type="single"

By specifying type="single", the date picker attaches to a single input, and the user can select a single date. This is the default selection type.

<amp-date-picker
  type="single"
  layout="fixed-height"
  height="360">
</amp-date-picker>

type="range"

By specifying type="range", the date picker attaches to two inputs, and the user can select a date range with a starting date and ending date.

<amp-date-picker
  type="range"
  layout="fixed-height"
  height="360">
</amp-date-picker>

Attributes

mode

Specifies how the date picker is rendered. Allowed values are:

  • static (default): The date picker renders as an interactive calendar view.
  • overlay: The date picker calendar view is not rendered until the user interacts with required input field(s) nested in the <amp-date-picker>.
type

Specifies the selection type for the date picker. Allowed values are:

  • single (default): The user can select a single date.
  • range: The user can select a date range.
input-selector

A query selector for a single date picker's input. If this is omitted, the date picker automatically generates a hidden input field, and assigns it a name of date or ${id}-date using the date picker's id. If either of these conflict with an existing element in the form, an error is emitted.

When amp-date-picker loads, the input element's value is used to display the initially selected date.

Specify the date property via the src attribute to set an initial date dynamically.

<amp-date-picker
    type="single"
    mode="overlay"
    layout="container"
    input-selector="[name=deliverydate]">
  <input type="text" name="deliverydate" placeholder="Delivery Date">
</amp-date-picker>
start-input-selector

A query selector for a date range picker's start date input. If this is omitted, the date picker automatically generates a hidden input field, and assigns it a name of start-date or ${id}-start-date using the date picker's id. If either of these conflict with an existing element in the form, an error is emitted.

When amp-date-picker loads, the input element's value is used to display the initially selected start date.

Specify the startDate property via the src attribute to set an initial end date dynamically.

<input id="a2">
<input id="b2">
<amp-date-picker
    type="range"
    start-input-selector="#a2"
    end-input-selector="#b2"
    layout="fixed-height" height="360">
</amp-date-picker>
end-input-selector

A query selector for a date range picker's end date input. If this is omitted, the date picker automatically generates a hidden input field, and assigns it a name of end-date or ${id}-end-date using the date picker's id. If either of these conflict with an existing element in the form, an error is emitted.

When amp-date-picker loads, the input element's value is used to display the initially selected end date.

Specify the endDate property via the src attribute to set an initial end date dynamically.

<input id="a2">
<input id="b2">
<amp-date-picker
    type="range"
    start-input-selector="#a2"
    end-input-selector="#b2"
    layout="fixed-height" height="360">
</amp-date-picker>
min

The earliest date that the user may select. If no min attribute is present, the current date will be the minimum date.

max

The latest date that the user may select. If no max attribute is present, the date picker will have no maximum date.

month-format

The format to use for displaying the month in the calendar view. The default format is: "MMMM YYYY".

format

The format to use for displaying and parsing the date in the input boxes. The default format is "YYYY-MM-DD".

week-day-format

The format to use for displaying the day of the week in the calendar view. If no week-day-format is present, the weekdays display as the first character of the weekday.

<amp-date-picker
    type="single"
    mode="overlay"
    layout="container"
    format="MM/DD/YYYY"
    week-day-format="ddd"
    input-selector="[name=date]">
  <input type="text" name="date" placeholder="Your Date">
</amp-date-picker>
locale

The locale to use for rendering the calendar view. The default locale is "en".

number-of-months

The number of months to display at one time in the calendar view. The default is "1".

first-day-of-week

The day to specify as the first day of the week (0-6). The default value is "0" (Sunday).

blocked

A list of ISO 8601 dates or RFC 5545 RRULE repeating dates to prevent the user from selecting on the calendar.

highlighted

A list of ISO 8601 dates or RFC 5545 RRULE repeating dates to specially style as highlighted to draw the user's attention. Default styling is a blue dot on the date.

day-size

The size in px of the date cells in the calendar view table. The default is 39.

Note: due to a bug, a non-default day-size causes the date picker height to be incorrect on months that span more than 4 weeks. To prevent incorrect height, add a CSS rule to the document that sets a minimum height for the date picker.

.amp-date-picker-resize-bug .DayPicker_transitionContainer {
  min-height: 354px; /* 354px is the default. You must update it. */
}
allow-blocked-ranges

If present, this attribute prevents the user from selecting a range with a blocked date. By default, this attribute is not present.

src

If present, amp-date-picker requests JSON data to populate certain attributes dynamically, as well as matching lists of dates to template ids for rendering days in the calendar.

If your calendar data is personalized for the user or updates often, these values should be specified in the src JSON response and not with their corresponding attributes on the amp-date-picker element.

The following table lists the properties that you can specify in the JSON data:

src
property
Description
blocked An array of ISO 8601 single dates or RFC 5545 RRULE repeating dates to render as blocked in the calendar view. The user is prevented from selecting these dates.
date Specifies the initially selected date. In a date picker with type="range" this has no effect.
endDate Specifies the initially selected end date. In a date picker with type="single" this has no effect.
highlighted An array of ISO 8601 single dates or RFC 5545 RRULE repeating dates to render as highlighted in the calendar view.
startDate Specifies the initially selected start date for a date picker with type="range". In a date picker with type="single" this has no effect.
templates The templates property is an array of "template definition objects". These objects have an id property and a dates property.
template definition objects

The dates property is an array of ISO 8601 single dates or RFC 5545 RRULE repeating dates. The id property specifies the id of a template that the date picker can use to render the specified dates in the calendar view.

{
  "id": "my-template-id",
  "dates": [
    "2018-01-02",
    "FREQ=WEEKLY;DTSTART=20180101T000000Z;COUNT=52;WKST=SU;BYDAY=TU"
  ]
}

If no dates property is specified in a template definition object, the template with the given id will be used as the default template to render any dates that do not have an explicitly specified template.

{"id": "my-default-template-id"}

Example: Specifying properties via the src attribute

{
  "blocked": ["2018-02-14"],
  "highlighted": ["2018-02-15"],
  "templates": [
    {
      "id": "my-template-id",
      "dates": ["2018-01-01"]
    },
    {
      "id": "my-second-template-id",
      "dates": [
        "2018-01-02",
        "FREQ=WEEKLY;DTSTART=20180101T000000Z;COUNT=52;WKST=SU;BYDAY=TU"
      ]
    },
    {
      "id": "my-default-template-id"
    }
  ],
  "startDate": "2018-01-01",
  "endDate": "2018-02-02",
  "date": "2018-02-03"
}

Example: Markup using the src attribute

<amp-date-picker src="https://www.example.com/date-data.json"
  layout="fixed-height" height="360">
  <template type="amp-mustache" date-template id="my-template-id">⚡️</template>
  <template type="amp-mustache" date-template id="my-second-template-id">🌮</template>
  <template type="amp-mustache" date-template id="my-default-template-id">{{D}}</template>
</amp-date-picker>
fullscreen

Renders the picker to fill the space available to it, like in a fullscreen lightbox. This works best with layout="fill".

<input on="tap:lightbox.open" placeholder="Start" id="start">
<input on="tap:lightbox.open" placeholder="End" id="end">
<button on="tap:dp.clear">Clear</button>
<amp-lightbox id="lightbox" layout="nodisplay">
  <amp-date-picker
    id="date-picker"
    layout="fill"
    fullscreen
    type="range"
    number-of-months="12"
    start-input-selector="#start"
    end-input-selector="#end"
    on="
      activate: lightbox.open;
      deactivate: lightbox.close"
  ></amp-date-picker>
</amp-lightbox>

open-after-select

If present, keeps the date picker overlay open after the user selects a date or dates. By default, this attribute is not present.

open-after-clear

If present, keeps the date picker open after the user clears the date or dates. By default, this attribute is not present.

common attributes

This element includes common attributes extended to AMP components.

Events

These events may trigger actions on other AMP components using the on attribute. e.g. on="activate: my-lightbox.open"

Read more about AMP Actions and Events.

activate

The date picker triggers the activate event when the user begins an interaction with the calendar view, i.e. when the overlay would open.

deactivate

The date picker triggers the deactivate event when the user ends their interaction with the calendar view, i.e. when the overlay would close.

Actions

These actions may be triggered by other components using the on attribute. e.g. on="tap: date-picker.setDate(date=state.value)"

Read more about AMP Actions and Events.

clear

The clear action clears the date value or values from the single date picker or date range picker with the specified id, e.g. date-picker.

<button on="tap: date-picker.clear">Clear</button>
setDate

The setDate action assigns the value of the date argument to the single date picker with the specified id, e.g. date-picker.

<button on="tap: date-picker.setDate(date='2018-01-01')">
  Set to Jan 1, 2018
</button>
setDates

The setDate action assigns the value of the start and end arguments to the date range picker with the specified id, e.g. date-picker.

<button on="tap: date-picker.setDates(start='2018-01-01', end='2018-01-07')">
  Set to Jan 1, 2018 through Jan 7, 2018
</button>
today

The today action assigns the value of the current day, plus an offset argument, to the single date picker with the specified id, e.g. date-picker. The offset argument value can be any integer.

<button on="tap: date-picker.today">Today</button>
<button on="tap: date-picker.today(offset=1)">Tomorrow</button>
<button on="tap: date-picker.today(offset=-1)">Yesterday</button>
startToday

The startToday action assigns the value of the current day, plus an offset argument, to the date range picker with the specified id, e.g. date-picker. The offset argument value can be any integer.

<button on="tap: date-picker.startToday">Today</button>
<button on="tap: date-picker.startToday(offset=1)">Tomorrow</button>
<button on="tap: date-picker.startToday(offset=-1)">Yesterday</button>

The startToday action can be combined with the endToday action to select ranges with an offset.

<button
  on="tap:date-picker.startToday(offset=7), date-picker.endToday(offset=14)">
  Next week
</button>
endToday

The endToday action assigns the value of the current day, plus an offset argument, to the date range picker with the specified id, e.g. date-picker. The offset argument value can be any integer.

<button on="tap: date-picker.endToday">Today</button>
<button on="tap: date-picker.endToday(offset=1)">Tomorrow</button>
<button on="tap: date-picker.endToday(offset=-1)">Yesterday</button>

The endToday action can be combined with the startToday action to select ranges with an offset.

<button
  on="tap:date-picker.startToday(offset=7), date-picker.endToday(offset=14)">
  Next week
</button>

Templates

amp-date-picker provides a markup API to render templates for certain dates and for an extra information area below the calendar view.

date-template

amp-date-picker consumes templates specified in HTML markup to render dates. These templates must only be used for dates that will not need to be updated often, like holidays. For rendering special information in the calendar days like days with sales, or amounts of money, or other information that must change often, consider using the src attribute instead. Using src prevents chached AMP documents from showing out-of-date information.

A date-template must have a dates or default attribute.

  • dates: A space-separated list of ISO 8601 single dates or RFC 5545 RRULE repeating dates. The template content will render for the dates matching the dates in the attribute.

  • default: If the default attribute is present, the template content will render for all dates not matching an existing template.

The date picker provides mustache variables to render in the templates. These variables are ISO 8601 format string values e.g. DD, D, X, etc.

date-templates may contain any valid AMP content and are only rendered after the calendar view renders for the first time.

<amp-date-picker layout="fixed-height" height="360">
  <!-- Render the "party" emoji on New Years Day 2018 -->
  <template type="amp-mustache" date-template dates="2018-01-01">🎉</template>
  <!-- Render the "taco" emoji every Tuesday for 52 weeks starting 2018-01-01 -->
  <template
      type="amp-mustache"
      date-template
      dates="FREQ=WEEKLY;DTSTART=20180101T000000Z;COUNT=52;WKST=SU;BYDAY=TU"
  >🌮</template>
  <!-- Render an image -->
  <template type="amp-mustache" date-template dates="2018-01-02">
    <amp-img layout="fixed-height" height="39" src="./example.jpg"></amp-img>
  </template>
  <!-- Renders dates in the two-digit day format -->
  <template type="amp-mustache" date-template default>{{DD}}</template>
</amp-date-picker>
info-template

The info-template contains markup to render in an information area below the calendar view. info-templates may contain any valid AMP content and are only rendered after the calendar view renders for the first time.

<amp-date-picker layout="fixed-height" height="360">
  <template type="amp-mustache" info-template>
    Warning: Tacos are only available on Tuesday
  </template>
</amp-date-picker>

Validation

See amp-date-picker rules in the AMP validator specification.