Skip to main contenteBay Playbook

Date picker

v1.2.0

Date pickers allow users to choose a date or a range of dates.

Stylized graphic of a date picker.

Anatomy

Anatomy of a date picker. Number 1 points to the month navigator chevrons. Number 2 points to the days of the week. Number 3 points to the date cells. Number 4 points to the current date. Number 5 points to the date range start. Number 6 points to the month and year. Number 7 points to the date range end. Number 8 points to the container. Number 9 points to the selected date range.
  1. Month navigators
  2. Days
  3. Date range start
  4. Month and year
  5. Date range selected
  6. Date cell
  7. Current date
  8. Date range end
  9. Container

Properties

Default picker

The default picker allows for a single date selection. The current date is always visible.

Dates can be disabled if they are outside of the allowed time range. This can be days prior to the current day for scheduling events, or a maximum date range for events in the past.

A default picker for the month of September. The current date is the 1st. The selected date is the 19th.

Date range picker

The date picker can also allow the selection of a range of dates. The first tap sets the starting date and a second tap sets the ending date. A third tap resets the date range and sets the new starting date.

A default picker for the month of September. The current date is the 3rd. The starting date is the 16th and the ending date is the 20th.

Double picker

On larger screens, two months can be shown at a time using the double picker. This larger picker behaves the same as the single picker when navigating, selecting, and setting date ranges.

A double picker for the months of September and October. The current date is Sep 3rd. The starting date is Sep 16th and the ending date is Sep 20th.

Date input

The date picker is typically triggered by a date input field. Simple, memorable dates will accept text input with the option to reveal a date picker calendar when interacting with the calendar icon.

Different states of a date input. The first is a placeholder with mm/dd/yyyy. The second has a date input 07/21/2025. The last is an error with an alert with “Enter a date”.

Behavior

Navigating months

Both single and double pickers navigate horizontally via the top-right controls or by swiping left or right on the dates. Full screen dialog pickers scroll vertically.

A single default picker with a swiping indicator from right to left.
A full screen dialog picker with a swiping indicator from bottom to top.

State

There are multiple states for dates to indicate if they can be selected, if they are selected, what the current day is, and whether a range is set.

Staes for dates. From left to right are inactive enabled, focused enabled, current enabled, active enabled, active enabled start, active enabled end, inactive enabled middle, empty disabled, and inactive disabled.

Platforms

Native pickers

Native Android and iOS devices leverage the OS date pickers.

An Android-styled date picker.

Android date picker

An iOS-styled date picker.

iOS date picker

Android

Android devices use the Material date picker component. The Material date picker is available in a docked popover or modal variant.

A material design docked date picker popover.
A material design modal date picker on a mobile screen. The months are stacked.

iOS

iOS devices use the native picker components. These are available as popovers or inline pickers.

An iOS popover date picker.
An iOS inline date picker.

Screen sizes

Small

Date pickers in native apps use the OS pickers. HTML uses the popover or fullscreen dialog version.

A native iOS date picker in popover form.

Native date picker

A small screen html date picker as a fullscreen modal.

HTML full screen date picker

Large

Date pickers in native apps on tablet use the native OS pickers. HTML uses the popover pickers.

A large screen html example using the double date picker popover.

Best practices

Choosing a picker

Do allow users to quickly enter short dates or times.

Simple date entry in a text input for a credit card expiration date.

Don’t use a date or time picker when text entry would be quicker and more convenient.

A date picker used in a text input for a credit card expiration date.

Specs

Specs for a default date picker. There is 16px padding around the container. The month and year along with pagination controls are 24px tall. Each pagination control has 16px on the sides. 16px is between the header portion and the day row. The day row is 20px tall. The date selector cells are 48px tall. The selection circles on the dates are 32px tall with 8px above and below equaling the 48px of the cell.

Default picker

Specs for a double date picker. The specs are the same as the default date picker, but there are two months next to each other.

Double picker

Specs for a double date picker in vertical format. There is 16px on the left and right. The days title container is 40px tall with the dates being 20px tall. The month titles are 24px tall. There is 8px between the month titles on the date cells. The date cells are 48px tall. The circular selections over the numbers are 32px tall with 8px above and below equalling the 48px. There is 16px between months.

Vertical double picker

The different colors used for the states. foreground.primary is used for the day selector text. state-layer.selected is used for the range selector background color. foreground.disabled is used for disabled text. state-layer.pressed is used for the pressed state. border-strong is used for the current date. background.inverse is used for the selected date circle. foreground.on-inverse is used for the text inside. state-layer.selected is used for the starting and ending range selector.

Selection states

Change log

VersionDateNotes
1.2.0
Aug, 2024
  • Updated to eBay Evo
1.2.0
Feb, 2023
  • Added keyboard interaction specs
1.1.0
Jan, 2023
  • Added nested instance property for header component to parent date picker component
  • Renamed calendar header layer to “header”
  • Replaced “Calendar” in atomic layer names to “DatePicker”
1.0.0
Jul, 2022
  • Initial release