DatePicker
betaPicks 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
Deployment date with min and max
Required, with hint
With error message
Clearable
No weekends or holidays
With day marks
Compact density
Loading
Date range
With date presets
Range with presets
Typed date
Several months
Month and year selector
Week number
Date and time
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-textadds 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-maxto restrict it to valid dates, anddata-ts-disabled-weekdays,data-ts-disabled-dates, orsetDatePickerDisabledDatefor individual days that can’t be picked. - Use
data-ts-day-marksto flag events with a dot and a short label. Screen readers announce the label, and it’s also used as thetitle. - Call
setDatePickerLoading(root, true)while you fetch marks or unavailable days from the server. It doesn’t block the field. - Build it with the
fieldmarkup 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), usereadonly, notdisabled, 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-rangeinside a form, put anameon both<input type="hidden">elements (data-ts-date-input="start"and"end"). Twoyyyy-mm-dddates 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-textif people only choose among a few dates on the calendar. An editable field invites typos that the calendar avoids. - Don’t expect
ts:changeon 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
todayas 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.
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-cleardata-ts-count-suffixdata-ts-date-captiondata-ts-date-griddata-ts-date-inputdata-ts-date-monthsdata-ts-date-nextdata-ts-date-pickerdata-ts-date-presetdata-ts-date-prevdata-ts-date-spinnerdata-ts-date-statusdata-ts-date-textdata-ts-date-timedata-ts-date-titledata-ts-date-weekdaysdata-ts-day-marksdata-ts-disabled-datesdata-ts-disabled-weekdaysdata-ts-end-textdata-ts-granularitydata-ts-hour-cycledata-ts-listboxdata-ts-listbox-labeldata-ts-listbox-loadingdata-ts-listbox-nativedata-ts-listbox-paneldata-ts-listbox-spinnerdata-ts-listbox-triggerdata-ts-localedata-ts-monthdata-ts-numberdata-ts-number-fielddata-ts-number-formatdata-ts-number-rawdata-ts-number-spinnerdata-ts-number-stepdata-ts-placeholderdata-ts-rangedata-ts-required-proxydata-ts-valuedata-ts-visible-monthsdata-ts-week-columndata-ts-week-numbersdata-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-max | Days out of range are aria-disabled—focusable, but not selectable. |
data-ts-week-start="0" | The first day of the week. |
data-ts-locale | The language of month and day names, and of the date format. |
placeholder, disabled, size, density | The usual ones: native attributes and the component’s classes. It also works in RTL. |
data-ts-disabled-dates | Unavailable days, separated by spaces, for example "2026-12-25 2027-01-01". |
data-ts-disabled-weekdays | Unavailable days of the week, for example "0 6". |
setDatePickerDisabledDate(root, fn) | A function decides which days are unavailable. null removes it. |
data-ts-day-marks | Per-day marks, as JSON, for example [{"date":"2026-12-25","label":"Deployment","variant":"success"}]. |
data-ts-visible-months | How 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-numbers | A 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-cycle | Date 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-preset | Presets. 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-block | Prefix. A span first in the trigger, or a div first in div.ts.datepicker-field. It’s markup and CSS. |
data-ts-date-text | Typeable 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-range | Range, 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:change | Choosing 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.csstaisho.checkbox.csstaisho.icon.csstaisho.input.csstaisho.kbd.csstaisho.number-input.csstaisho.popover.csstaisho.select.csstaisho.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>witharia-haspopup="dialog"and anaria-expandedthat reflects whether the calendar is open (also in Core, which syncs it when thepopoveropens and closes). The panel is arole="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
gridcellwhose accessible name is the full date.aria-selectedmarks the chosen day, and days out of range carryaria-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 firingts:change.- The trigger is named through
aria-labelledby(label + chosen date), andaria-describedbypoints to the hint or the error. An invalid field carriesaria-invalid="true", and the message is announced witharia-live="polite". The required asterisk is decorative (aria-hidden). A<button>supports neitherrequirednoraria-required, so an<input data-ts-required-proxy>blocks submission instead—noname, 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 whendisabledorreadonly. - Unavailable days (
data-ts-disabled-dates,data-ts-disabled-weekdays, or a function set withsetDatePickerDisabledDate(root, fn)) carryaria-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 thetitle. The colored dot is decorative (aria-hidden). Color is never the only cue. - For the loading state, call
setDatePickerLoading(root, true|false). It setsis-loadingandaria-busy="true"on the trigger and the grid, and shows a Spinner (arole="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 namedrole="group". A preset that falls outside the allowed range, or whose start or end is an unavailable day, carriesaria-disabled="true". Like the days, it stays focusable and can’t be selected. Each preset carries a key (today,last-7-days,this-week…), ayyyy-mm-ddday, or aninicio/fininterval. Keys are resolved against today on click, and Core recomputesaria-disabledevery time the panel opens. - With
data-ts-range, the grid carriesaria-multiselectable="true", andaria-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 withIntl.DateTimeFormat.formatRange. Both ends must be available days. The range can span days witharia-disabled. You declare the value withdata-ts-value="inicio/fin", andts:changecarriesstartandend. - 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 byaria-labelif there isn’t one). Itsaria-describedbyadds hidden text with the expected format (“Format: mm/dd/yyyy”), and the same pattern is theplaceholder. The separate calendar button carriesaria-label,aria-haspopup="dialog", andaria-expanded.required,readonly, anddisabledare the input’s native attributes (the validation message is the browser’s, and no proxy input is needed). Withreadonly, there’s no button. In range mode, the two fields live in arole="group"named by the label, and each one has its ownaria-label(“Start date” / “End date”).aria-invalidandaria-busygo on the inputs. readonlykeeps the trigger focusable and notdisabled, but withoutaria-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 carryaria-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 withts: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 usesHighlight/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 ownrole="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 througharia-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 througharia-livewhen 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 arole="rowheader"named “Week 29” (translatable), and the column has its owncolumnheader. 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 arerole="spinbutton"fields (arrow keys, Page Up, and Page Down) inside arole="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/End | First and last day of the week. |
| Page Up/Page Down | Previous and next month. If the day doesn’t exist in that month, it lands on the last day. |
| Shift+Page Up/Page Down | Previous and next year. |
| Enter/Space | Selects 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.