Skip to content

DatePicker

beta

Picks a date. An input-style trigger opens a keyboard-navigable calendar (APG pattern). It works with the native Date and zero dependencies; month and day names come from Intl. The panel lives in the native top layer (Popover API). With data-ts-range it picks a span (start and end) in the same calendar, data-ts-date-preset adds shortcuts (today, last 7 days, this month) in a column next to the grid, and data-ts-date-text lets users type the date in a text field.

Forms · TaishoDS Core, in plain HTML.

Examples

One working example per case. Each example is the HTML of its preview—copy it as is, and with Core’s CSS and JS loaded, it looks and works the same.

Standalone calendar

html

Deployment date with min and max

html

Required, with hint

html

With error message

html

Clearable

html

No weekends or holidays

html

With day marks

html

Compact density

html

Loading

html

Date range

html

With date presets

html

Range with presets

html

Typed date

Format: mm/dd/yyyy
html

Several months

html

Month and year selector

html

Week number

html

Date and time

html

When to use

  • Capturing a date where seeing the calendar helps people choose (bookings, due dates).
  • You need a span with a start and end (a deployment window, a billing period). Use data-ts-range.
  • The context of the month or week matters for the decision.
  • People know the date by heart or paste it from somewhere else (a due date, a ticket). data-ts-date-text adds a field to type it in.
  • Some choices come up again and again (today, the last 7 days, this month). Add them as shortcuts with data-ts-date-preset.
  • You need to restrict it to a range (data-ts-min/data-ts-max) or respect a locale (data-ts-locale).
  • You want the complete field, with a label, hint, and error.
  • Some days can’t be picked (weekends, holidays, a custom rule), or should be flagged with a mark (meetings, deployments).

When not to use

  • The date is known and typing is faster (a date of birth) → a formatted input.
  • It’s only a time, with no date, or a value that isn’t a date → the matching control.

Do

  • Use data-ts-min/data-ts-max to restrict it to valid dates, and data-ts-disabled-weekdays, data-ts-disabled-dates, or setDatePickerDisabledDate for individual days that can’t be picked.
  • Use data-ts-day-marks to flag events with a dot and a short label. Screen readers announce the label, and it’s also used as the title.
  • Call setDatePickerLoading(root, true) while you fetch marks or unavailable days from the server. It doesn’t block the field.
  • Build it with the field markup for forms, or keep its label, hint, and error next to the field when it stands alone. Make the expected format clear.
  • In the typeable field (data-ts-date-text), use readonly, not disabled, to show a date that can’t be edited. It stays focusable and reads better.
  • For relative shortcuts, use the keys (today, last-7-days, last-30-days, this-week, this-month, last-month). They’re resolved on click, not when the page is built.
  • With data-ts-range inside a form, put a name on both <input type="hidden"> elements (data-ts-date-input="start" and "end"). Two yyyy-mm-dd dates are submitted, start and end.

Don’t

  • Don’t make people page through months to reach a distant date they already know.
  • Don’t turn on data-ts-date-text if people only choose among a few dates on the calendar. An editable field invites typos that the calendar avoids.
  • Don’t expect ts:change on the first click of a range. It only fires once the range is complete or cleared.
  • Don’t pass a range key to a single-date calendar (or today as a multi-day range). It isn’t drawn, and you get a warning in development.
  • Don’t assume a format. Respect the user’s locale.
  • Don’t rely on the mark’s color alone. Always write its label.

Related

FieldInput

TaishoDS Core

Needs Core’s JS, which handles focus, keyboard, and state.

It’s its own calendar with keyboard navigation. The native <input> only provides the text field.

Core hooks into it through these attributes. They go in the markup, and there’s nothing to initialize.

  • data-ts-clear
  • data-ts-count-suffix
  • data-ts-date-caption
  • data-ts-date-grid
  • data-ts-date-input
  • data-ts-date-months
  • data-ts-date-next
  • data-ts-date-picker
  • data-ts-date-preset
  • data-ts-date-prev
  • data-ts-date-spinner
  • data-ts-date-status
  • data-ts-date-text
  • data-ts-date-time
  • data-ts-date-title
  • data-ts-date-weekdays
  • data-ts-day-marks
  • data-ts-disabled-dates
  • data-ts-disabled-weekdays
  • data-ts-end-text
  • data-ts-granularity
  • data-ts-hour-cycle
  • data-ts-listbox
  • data-ts-listbox-label
  • data-ts-listbox-loading
  • data-ts-listbox-native
  • data-ts-listbox-panel
  • data-ts-listbox-spinner
  • data-ts-listbox-trigger
  • data-ts-locale
  • data-ts-month
  • data-ts-number
  • data-ts-number-field
  • data-ts-number-format
  • data-ts-number-raw
  • data-ts-number-spinner
  • data-ts-number-step
  • data-ts-placeholder
  • data-ts-range
  • data-ts-required-proxy
  • data-ts-value
  • data-ts-visible-months
  • data-ts-week-column
  • data-ts-week-numbers
  • data-ts-week-short

What it does: Draws the calendar grid, handles keyboard navigation, and formats the date. With a trigger it’s fully functional, with the calendar in a panel that opens, closes, and returns focus. Each day’s accessible name is the full date. If the attributes below change through JavaScript, the calendar redraws.

Attribute What it does
popovertarget (on the trigger)The button opens the calendar with the native Popover API and keeps aria-expanded and is-open in sync. On open, the calendar goes back to the value’s month, with focus on its day. Choosing a day (click, Enter, or Space) closes the panel, writes the formatted date in the trigger and the yyyy-mm-dd value in the <input type="hidden" name>, and returns focus to the button. Esc and clicking outside close it. Shift + Page Up/Page Down move by year.
data-ts-min, data-ts-maxDays out of range are aria-disabled—focusable, but not selectable.
data-ts-week-start="0"The first day of the week.
data-ts-localeThe language of month and day names, and of the date format.
placeholder, disabled, size, densityThe usual ones: native attributes and the component’s classes. It also works in RTL.
data-ts-disabled-datesUnavailable days, separated by spaces, for example "2026-12-25 2027-01-01".
data-ts-disabled-weekdaysUnavailable days of the week, for example "0 6".
setDatePickerDisabledDate(root, fn)A function decides which days are unavailable. null removes it.
data-ts-day-marksPer-day marks, as JSON, for example [{"date":"2026-12-25","label":"Deployment","variant":"success"}].
data-ts-visible-monthsHow many months show at once. Core draws one grid per month inside div.ts.calendar-months[data-ts-date-months], which replaces the single grid. The root carries is-multi.
data-ts-caption-layout="dropdown"Month and year selector. The header holds two Selects with data-ts-date-caption="month" and "year" on their triggers, each with its current option. Core uses that option as a template and fills in the rest from data-ts-min and data-ts-max.
data-ts-week-numbersA column with the ISO week. Its value is the accessible name of each number, with {n} in place of the number ("Week {n}"). data-ts-week-short is the header text and data-ts-week-column its accessible name. The root carries has-week-numbers.
data-ts-granularity="minute", data-ts-hour-cycleDate with time, single mode only. data-ts-value, data-ts-min, data-ts-max, and the hidden input use yyyy-mm-ddThh:mm in local time. Below the grid, inside div.ts.calendar-time, go two NumberInputs with data-ts-date-time="hour" and "minute" on their inputs and, with data-ts-hour-cycle="12", a Select with "period" on its trigger. Picking a day doesn’t close the panel.
data-ts-date-presetPresets. Buttons inside div.ts.datepicker-presets[role=group] in the panel, each with a key (today, last-7-days…), a yyyy-mm-dd day, or an inicio/fin interval. They confirm and close like choosing a day, and become aria-disabled when they fall outside min/max or aren’t available.
ts datepicker-prefix-blockPrefix. A span first in the trigger, or a div first in div.ts.datepicker-field. It’s markup and CSS.
data-ts-date-textTypeable field. A div.ts.datepicker-field with input.ts.datepicker-input[data-ts-date-text] ("start" and "end" with range, inside role=group) and the .ts.datepicker-toggle button with popovertarget. Core commits on blur or on Enter (without consuming the key, so a <form> still submits), writes the hidden input, and reformats. An invalid, out-of-range, or unavailable value reverts to the last valid one, and an empty field clears the date (ts:change with an empty value). required, readonly, and disabled are the input’s native attributes.
data-ts-rangeRange, on the calendar root. data-ts-value is the ISO interval (2026-07-01/2026-07-31). The first click sets the start, the preview follows the pointer and focus, a live region announces the start (template data-ts-end-text), and there are two hidden inputs, data-ts-date-input="start" and "end". ts:change carries value, start, and end, and only fires when the range is completed or cleared.
setDatePickerLoading(root, true | false)Sets is-loading, aria-busy, and the data-ts-date-spinner Spinner. It doesn’t block.
ts:changeChoosing a day fires it, and it’s cancelable. form.reset() returns to the initial date without firing it.

From the CDN, without a build, load taisho.date-picker.css along with taisho.base.css. Also load:

  • taisho.button.css
  • taisho.checkbox.css
  • taisho.icon.css
  • taisho.input.css
  • taisho.kbd.css
  • taisho.number-input.css
  • taisho.popover.css
  • taisho.select.css
  • taisho.spinner.css

For how Core works in general, see Behavior.

Accessibility

Implements the Date Picker Dialog pattern from the WAI-ARIA APG.

  • The trigger is a <button> with aria-haspopup="dialog" and an aria-expanded that reflects whether the calendar is open (also in Core, which syncs it when the popover opens and closes). The panel is a role="dialog" with an accessible name.
  • The grid uses role="grid" with a roving tabindex. Arrow keys move by day/week, Home/End go to the start/end of the week, Page Up/Page Down change the month (with Shift, the year), and Enter/Space select. The group and the grid are named after the visible month (“July 2026”).
  • Each day is a gridcell whose accessible name is the full date. aria-selected marks the chosen day, and days out of range carry aria-disabled (they stay focusable but can’t be selected). The name is the full date, not just the day number.
  • form.reset() restores the initial date (trigger text, hidden input, and calendar) without firing ts:change.
  • The trigger is named through aria-labelledby (label + chosen date), and aria-describedby points to the hint or the error. An invalid field carries aria-invalid="true", and the message is announced with aria-live="polite". The required asterisk is decorative (aria-hidden). A <button> supports neither required nor aria-required, so an <input data-ts-required-proxy> blocks submission instead—no name, invisible, aria-hidden, and out of the Tab order. Submitting it empty shows the browser’s native message, and focus lands on the trigger. It doesn’t validate when disabled or readonly.
  • Unavailable days (data-ts-disabled-dates, data-ts-disabled-weekdays, or a function set with setDatePickerDisabledDate(root, fn)) carry aria-disabled="true". They stay focusable with the arrow keys (APG), but Enter, Space, and click don’t select them. The calendar redraws if they change through JS.
  • Day marks (data-ts-day-marks) add the mark’s text to the cell’s accessible name (“Thursday, December 25, 2026, Christmas”; several marks are joined with commas) and repeat it in the title. The colored dot is decorative (aria-hidden). Color is never the only cue.
  • For the loading state, call setDatePickerLoading(root, true|false). It sets is-loading and aria-busy="true" on the trigger and the grid, and shows a Spinner (a role="status" that announces the state). If you set only the class, it isn’t announced. It doesn’t block, so the calendar opens and you can pick a date.
  • Presets (data-ts-date-preset) are buttons inside a named role="group". A preset that falls outside the allowed range, or whose start or end is an unavailable day, carries aria-disabled="true". Like the days, it stays focusable and can’t be selected. Each preset carries a key (today, last-7-days, this-week…), a yyyy-mm-dd day, or an inicio/fin interval. Keys are resolved against today on click, and Core recomputes aria-disabled every time the panel opens.
  • With data-ts-range, the grid carries aria-multiselectable="true", and aria-selected="true" is set on the whole range (both ends and everything in between, including the preview). After the first click, a live region (role="status", data-ts-date-status) announces “Start: Tuesday, July 14, 2026. Pick an end date.” and is emptied when the range is completed or discarded. The trigger shows the range with Intl.DateTimeFormat.formatRange. Both ends must be available days. The range can span days with aria-disabled. You declare the value with data-ts-value="inicio/fin", and ts:change carries start and end.
  • With the typeable field (data-ts-date-input, APG Date Picker Dialog pattern), the trigger is an <input type="text"> named by its label (or by aria-label if there isn’t one). Its aria-describedby adds hidden text with the expected format (“Format: mm/dd/yyyy”), and the same pattern is the placeholder. The separate calendar button carries aria-label, aria-haspopup="dialog", and aria-expanded. required, readonly, and disabled are the input’s native attributes (the validation message is the browser’s, and no proxy input is needed). With readonly, there’s no button. In range mode, the two fields live in a role="group" named by the label, and each one has its own aria-label (“Start date” / “End date”). aria-invalid and aria-busy go on the inputs.
  • readonly keeps the trigger focusable and not disabled, but without aria-haspopup, aria-expanded, or a calendar. Enter, Space, and click do nothing, and the value is still submitted with the form. It’s a <button>, so it doesn’t carry aria-readonly (it isn’t valid for its role).
  • The clear button (data-ts-clear) is a <button> sibling of the trigger, named “Clear field”. Tab reaches it after the trigger. Activating it closes the calendar, returns focus to the trigger, and reports the change with ts:change.
  • Today is marked with a dot under the number (in the text color, so it also contrasts on the selected day) as well as with font weight. With forced-colors, the underline counts instead of the dot. Day focus is a 2px inner ring in the family’s focus color, with no borders.
  • In RTL, the month chevrons are mirrored (previous points right). With forced-colors: active, the selected day uses Highlight/HighlightText, today is underlined (or gets a system dot if it’s also selected), and focus gets a system outline.
  • The text strings (previous/next month, “pick a date”) are written in the HTML. Month and day names come from Intl, based on the locale (data-ts-locale).
  • With data-ts-visible-months, each month is its own role="grid", named after its month. The whole calendar has a single tab stop, and the arrow keys cross from one grid to the next. The view only moves when the focused day leaves what’s visible, and the label with the month span is announced through aria-live. Filler days stay as empty cells so no date is read twice.
  • With data-ts-caption-layout="dropdown", the header adds two Selects named “Month” and “Year” (translatable), in the tab order between the arrows. The month label stays in the DOM for screen readers and is announced through aria-live when it changes. Escape with a select open closes only that select. After jumping to another month, the grid keeps its tab stop.
  • With data-ts-week-numbers, each row starts with a role="rowheader" named “Week 29” (translatable), and the column has its own columnheader. The number can’t be focused or selected, so the arrow keys keep moving from day to day.
  • With data-ts-granularity="minute", hours and minutes are role="spinbutton" fields (arrow keys, Page Up, and Page Down) inside a role="group" named “Time”, with translatable names. A 12-hour clock adds a Select for the time of day. Picking a day doesn’t close the panel and focus stays on the grid, so Tab reaches the time. With no date selected, the fields stay disabled. Escape closes the panel and keeps the value already chosen.

Keyboard

On top of what the browser already does (Tab moves focus, Enter activates a button).

Key What it does
←→↑↓Moves the focused day (by day and by week). In RTL, the grid is mirrored: ← moves forward one day and → moves back.
Home/EndFirst and last day of the week.
Page Up/Page DownPrevious and next month. If the day doesn’t exist in that month, it lands on the last day.
Shift+Page Up/Page DownPrevious and next year.
Enter/SpaceSelects the focused day, closes the calendar, and returns focus to the trigger.
Enter/Space(with`data-ts-range`)The first press sets the start, and the calendar stays open. The arrow keys move the range preview. The second press sets the end, closes, and returns focus to the trigger. Esc halfway through discards the start.
Tab(presets)With presets (data-ts-date-preset), Tab goes through the presets first (a column at the start of the panel) and then the calendar. On open, focus stays on the day. Enter, Space, or a click on a preset confirms the value, closes the panel, and returns focus to the trigger.
Type/Enter/Tab(`data-ts-date-input`)With the typeable field, clicking or tabbing into it doesn’t open the calendar (the calendar button is a separate tab stop, after the field). Enter or leaving the field confirms what was typed. If it’s unreadable, nonexistent, outside the allowed range, or an unavailable day, the text reverts to the last valid value, and an empty field clears the date. Inside a <form>, Enter lets the submission go through. In range mode, Tab moves from the start field to the end field without confirming. The pair is confirmed when focus leaves the group.
Enter/Space/click(trigger)Opens the calendar with focus on the focusable day (the selected one or, with no value, today). Esc closes it and returns focus to the trigger.

Verification

What was actually tested. Anything that wasn’t tested says so—we’d rather say “not verified” than claim too much.

  • axe WCAG 2.2 A + AA in a real browser, in light and dark mode, before every release.
  • keyboard Key map documented above, checked against the component.
  • screen reader Not verified with a screen reader. Test it in your own combination of components, not just here, where each one appears alone and on its happy path.