Date picker API · slotsmith

Slots

DatePicker has 15 slots. Pass a replacement for any of them in components; every slot you leave out keeps its fallback. Element slots receive DOM props, so a library's own element fits as it is; widget slots receive named props and usually need a few lines of adapter.

Name	Kind	Props it receives	Default fallback	`data-*` attributes
`Root`	<element>	DOM props: `Omit<HTMLAttributes<HTMLDivElement>, "color">` `ref?: Ref<HTMLDivElement>`	Fallback source `Root: ({ className, ...props }) => <div className={cx("sdp", className)} {...props} />`	`data-disabled` `data-empty` `data-invalid` `data-mode` `data-open`
`Trigger`	<element>	DOM props: `Omit<HTMLAttributes<HTMLDivElement>, "color">` `ref?: Ref<HTMLDivElement>`	Fallback source `Trigger: ({ className, ...props }) => <div className={cx("sdp__trigger", className)} {...props} />`	`data-disabled` `data-empty` `data-invalid` `data-open` `data-trigger`
`Input`	<element>	DOM props: `Omit<InputHTMLAttributes<HTMLInputElement>, "color" \| "size">` `ref?: Ref<HTMLInputElement>`	Fallback source `Input: ({ className, ...props }) => <input className={cx("sdp__input", className)} {...props} />`	`data-empty` `data-invalid` `data-open`
`Toggle`	<element>	DOM props: `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "color" \| "type">` `ref?: Ref<HTMLButtonElement>` `type?: "button"`	Fallback source `Toggle: ({ className, type = "button", ...props }) => ( <button type={type} className={cx("sdp__toggle", className)} {...props} /> )`	`data-open`
`Value`	{widget}	`text?: string` The formatted selection, when there is one. `placeholder: string` Shown when nothing is picked. `empty: boolean` Whether anything is picked.	Fallback source `Value: ({ text, placeholder, empty }) => ( <span className={cx("sdp__value", empty && "sdp__value--empty")}>{empty ? placeholder : text}</span> )`	—
`Icon`	{widget}	`open: boolean` Whether the calendar is open.	Fallback source `Icon: () => <CalendarIcon />`	—
`Clear`	{widget}	`onClick: () => void` Clears it. `aria-label: string` Accessible name.	Fallback source `Clear: ({ onClick, ...aria }) => ( <button type="button" className="sdp__clear" onClick={(event) => { event.stopPropagation(); onClick(); }} {...aria} > <CrossIcon /> </button> )`	—
`Popup`	<element>	DOM props: `Omit<HTMLAttributes<HTMLDivElement>, "color">` `ref?: Ref<HTMLDivElement>`	Fallback source `Popup: ({ className, ...props }) => <div className={cx("sdp__popup", className)} {...props} />`	`data-placement`
`Calendar`	<element>	DOM props: `Omit<HTMLAttributes<HTMLDivElement>, "color">` `ref?: Ref<HTMLDivElement>`	Fallback source `Calendar: ({ className, ...props }) => <div className={cx("sdp__calendar", className)} {...props} />`	—
`Caption`	{widget}	`month: ISODate` The month being shown, as the 1st of that month. `monthLabel: string` The month's name in the current locale. `monthIndex: number` The month being shown, `0` for January. `year: number` The year being shown. `months: string[]` Every month name, January first, for a dropdown. `years: number[]` The years that can be picked. `onMonthChange: (month: number) => void` Shows a different month of the same year. Takes a month index. `onYearChange: (year: number) => void` Shows the same month of a different year. `labels: { month: string; year: string }` Accessible names for the two controls.	Fallback source Caption: function Caption({ monthIndex, year, months, years, onMonthChange, onYearChange, labels }) { // An id rather than a name keeps the selects out of an enclosing form's submission. const id = useId(); return ( <span className="sdp__caption"> <select id={`${id}-month`} className="sdp__select" aria-label={labels.month} value={monthIndex} onChange={(event) => onMonthChange(Number(event.target.value))} > {months.map((name, index) => ( <option key={name} value={index}> {name} </option> ))} </select> <select id={`${id}-year`} className="sdp__select" aria-label={labels.year} value={year} onChange={(event) => onYearChange(Number(event.target.value))} > {years.map((value) => ( <option key={value} value={value}> {value} </option> ))} </select> </span> ); }	—
`Nav`	{widget}	`direction: "previous" \| "next"` Which way its arrow should point, as if the page were left to right. In right-to-left this is reversed for you: the control that moves back in time sits on the right and points right, so it is told `next`. `aria-label` always says what it does. `onClick: () => void` Moves the calendar. `disabled: boolean` Whether the move would leave the allowed range. `aria-label: string` Accessible name.	Fallback source `Nav: ({ direction, onClick, disabled, ...aria }) => ( <button type="button" className="sdp__nav" onClick={onClick} disabled={disabled} {...aria}> <ChevronIcon flip={direction === "next"} /> </button> )`	—
`Weekday`	{widget}	`label: string` The name in the current locale, in the chosen `weekdayFormat`. `name: string` The full name, e.g. "Saturday". `index: number` 0 to 6, in display order.	Fallback source `Weekday: ({ label }) => <span className="sdp__weekday">{label}</span>`	—
`Day`	<element>	DOM props: `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "color" \| "type">` `type?: "button"` `ref?: Ref<HTMLButtonElement>`	Fallback source `Day: ({ className, ...props }) => <button type="button" className={cx("sdp__day", className)} {...props} />`	`data-date` `data-disabled` `data-focused` `data-in-preview` `data-in-range` `data-outside` `data-range-end` `data-range-start` `data-selected` `data-today` `data-weekend`
`DayContent`	{widget}	`day: CalendarDay` The day being rendered. `selected: boolean` Whether it is picked. `inRange: boolean` Whether it sits inside a picked range. `inPreview: boolean` Whether it sits inside the range preview. `disabled: boolean` Whether it cannot be picked.	Fallback source `DayContent: ({ day }) => <span>{day.day}</span>`	—
`Footer`	{widget}	`presets: DatePickerPreset[]` The shortcuts to offer. `onPreset: (value: ISODate \| DateRange) => void` Applies one. `onToday: () => void` Jumps to today without picking it. `todayLabel: string` The label for that control — navigation, so it should read and look apart from the presets rather than like one of them.	Fallback source `Footer: ({ presets, onPreset, onToday, todayLabel }) => ( <div className="sdp__footer"> {presets.map((preset) => ( <button key={preset.label} type="button" className="sdp__preset" onClick={() => onPreset(preset.value)}> {preset.label} </button> ))} <button type="button" className="sdp__preset sdp__preset--today sdp__today" onClick={onToday}> <TodayIcon /> {todayLabel} </button> </div> )`	—

Props

Every prop of DatePicker, grouped as in the library's documentation. Controlled state comes in pairs: pass a value with its change handler, or only the default to leave the state inside the component.

Name	Type	Default	Description
Value and mode
`mode`single mode	`"single"`	—	One date. The default mode.
`mode`requiredmultiple mode	`"multiple"`	—	Any number of dates, toggled one click at a time.
`mode`requiredrange mode	`"range"`	—	A start and an end: the first click sets the start, the second the end.
`value`single mode	`ISODate \| null`	—	The picked date, or `null` for nothing.
`value`multiple mode	`ISODate[]`	—	The picked dates.
`value`range mode	`DateRange \| null`	—	The picked range. Either end may be missing while picking.
`defaultValue`single mode	`ISODate \| null`	—	The picked date while uncontrolled.
`defaultValue`multiple mode	`ISODate[]`	—	The picked dates while uncontrolled.
`defaultValue`range mode	`DateRange \| null`	—	The picked range while uncontrolled.
`onChange`single mode	`(value: ISODate \| null) => void`	—	The new date, or `null` when cleared.
`onChange`multiple mode	`(value: ISODate[]) => void`	—	The new dates, sorted, always an array.
`onChange`range mode	`(value: DateRange \| null) => void`	—	The new range, or `null` when cleared.
`clearable`	`boolean`	`true`	Whether the clear control is offered. Defaults to `true`.
`closeOnSelect`	`boolean`	`true` in single mode and `false` otherwise	Whether picking closes the popup. Defaults to `true` in single mode and `false` otherwise.
`valueFormat`	`DateValueFormat`	`"iso-datetime"`; `"YYYY-MM-DD"` keeps the calendar day alone	How the days the picker exchanges with you are written: `value`, `defaultValue`, `onChange`, `minDate`, `maxDate`, the presets and the day `disabledDates` is asked about. A pattern such as `"DD/MM/YYYY"`, `"iso-datetime"` for the instant the day starts in `timeZone`, or a codec of your own. Defaults to `"iso-datetime"`; `"YYYY-MM-DD"` keeps the calendar day alone.
`timeZone`	`string`	the browser's own	The time zone the calendar works in: an IANA name such as `"Asia/Tokyo"`, `"UTC"`, or an offset such as `"+09:00"`. Today is today in that zone, and with `valueFormat: "iso-datetime"` (the default) a picked day is the instant it starts there and an instant is read as the day it falls on there. Defaults to the browser's own.
`name`	`string`	—	The form field name. The root then holds a hidden input of that name per picked day, written as `valueFormat` says, so a plain HTML form submits the value: one day, each of several days, or a range's start then end.
Calendar
`locale`	`LocaleInput`	the provider's, then `en-US`	The language: a locale object, or a BCP 47 tag. A tag formats dates and names with `Intl` as always, and takes its labels from the pack of that language given to `SlotsmithProvider`, if there is one. Defaults to the provider's, then `en-US`.
`weekStartsOn`	`WeekStart`	the locale's own first day	The first column of the grid. Defaults to the locale's own first day.
`weekdayFormat`	`"narrow" \| "short" \| "long"`	`narrow`	How long the column headers are. `narrow` is a single character in every language, and is the only form that reliably fits a square day column. Defaults to `narrow`.
`presets`	`DatePickerPreset[]`	—	Shortcuts shown under the grid. A date preset in range mode picks that one day.
Bounds
`minDate`	`ISODate`	—	Nothing before this date can be picked, and the calendar does not page past it.
`maxDate`	`ISODate`	—	Nothing after this date can be picked, and the calendar does not page past it.
`disabledDates`	`(date: ISODate) => boolean`	—	Blocks individual dates — weekends, holidays, days already booked. They stay focusable.
Open state
`open`	`boolean`	—	Whether the popup is open.
`defaultOpen`	`boolean`	—	Whether the popup starts open.
`onOpenChange`	`(open: boolean) => void`	—	Told when the popup opens or closes.
`disabled`	`boolean`	—	Disables the whole control. Separate from `disabledDates`.
`invalid`	`boolean`	—	The value failed validation. Sets `aria-invalid` on the combobox and `data-invalid` on the root and trigger, so a skin can show its error style. Pair it with `aria-errormessage` or `aria-describedby` pointing at the message. Default `false`.
`onBlur`	`(event: FocusEvent<HTMLElement>) => void`	—	Told when focus leaves the whole control, for form libraries.
Display
`trigger`	`DatePickerTriggerKind`	—	What opens the calendar. `"input"`, the default, is a text field the date can be typed into, in the locale's numeric order (`MM/DD/YYYY` in en-US), with a calendar button beside it. `"button"` is one control that shows the formatted value and opens the calendar when pressed.
`openOnFocus`	`boolean`	`false`	With the `"input"` trigger, focusing or clicking the text field opens the calendar too. Defaults to `false`.
`placeholder`	`string`	—	Shown when nothing is picked. With the `"button"` trigger it defaults to `labels.placeholder`; the `"input"` trigger's text field shows the date order to type in, such as `MM/DD/YYYY`.
`format`	`Intl.DateTimeFormatOptions`	`{ day: "numeric", month: "short", year: "numeric" }`	How the trigger formats a date. Defaults to `{ day: "numeric", month: "short", year: "numeric" }`.
`placement`	`PopupPlacement`	`bottom`	Which side of the trigger the popup prefers. Defaults to `bottom`.
`popupOffset`	`number`	`4`	Gap between trigger and popup, in pixels. Defaults to 4.
`portal`	`PortalTarget`	`false`	Renders the popup in a portal: `true` for `document.body`, or an element of your own. It then escapes any ancestor's `overflow`, `transform` or stacking context, and still counts as part of the control. Set the `--ss-*` tokens and the dark class on `:root` or on that element, which the popup then inherits from. Defaults to `false`.
Slots and labels
`components`	`Partial<DatePickerComponents>`	—	Replace any part; the rest fall back to `SlotsmithProvider`'s `components.datePicker`, then to the built-in ones.
`labels`	`Partial<DatePickerLabels>`	—	Override any string. Wins over `locale`.
`slotProps`	`DatePickerSlotProps`	—	Extra DOM props for the element parts.

Any other prop is passed to the root <div> element.

Labels & locales

Every string DatePicker shows or announces, with its English default. Pass labels to change some of them for one component, or locale to switch every string to another language. The demo below does both.

Key	Type	English default	Description
`placeholder`	`string`	`"Pick a date"`	Trigger text when nothing is picked, and the trigger's default accessible name.
`clear`	`string`	`"Clear date"`	Accessible name for the clear control.
`openCalendar`	`string`	`"Open calendar"`	Accessible name for the calendar button beside the text field.
`previous`	`string`	`"Previous month"`	Accessible name for the previous-month control.
`next`	`string`	`"Next month"`	Accessible name for the next-month control.
`today`	`string`	`"Go to today"`	Label for the control that jumps to today's month without picking it — a navigation verb, not the bare word "today", so it reads apart from the presets.
`month`	`string`	`"Month"`	Accessible name for the month dropdown.
`year`	`string`	`"Year"`	Accessible name for the year dropdown.
`dialog`	`string`	`"Choose a date"`	Accessible name for the popup.
`count`	`(count: number) => string`	`count(3)` prints `"3 dates selected"`	Multiple mode: how the trigger summarises more than two dates.
`rangeStart`	`(from: string) => string`	`rangeStart("Mar 3")` prints `"Mar 3 — …"`	Range mode, when only the start is picked. Receives the formatted start.
`range`	`(from: string, to: string) => string`	`range("Mar 3", "Mar 9")` prints `"Mar 3 — Mar 9"`	Range mode, when both ends are picked. Receives both formatted ends.

import { DatePicker } from "slotsmith/date-picker";
import { de } from "slotsmith/locales/de";

export default function Labels() {
  return (
    <DatePicker
      mode="multiple"
      // Every string in German, from the ready-made pack; month and weekday names come from Intl…
      locale={de}
      // …except these two, replaced for this picker only.
      labels={{ openCalendar: "Kalender zeigen", today: "Heute anzeigen" }}
      aria-label="Urlaubstage"
    />
  );
}

The ready-made language packs, right-to-left support and app-wide locales are on the Languages page.

Styling

The class names the fallbacks of DatePicker put on their elements, and the tokens its stylesheet reads. Set a token on the component, or on any element around it, to restyle it; target a class only for what no token covers.

Class	Slot
`.sdp`	`Root`
`.sdp__header`	—
`.sdp__cell`	—
`.sdp__weekdays`	—
`.sdp__columnheader`	—
`.sdp__week`	—
`.sdp__chevron`	—
`.sdp__icon`	`Icon`
`.sdp__today-icon`	—
`.sdp__clear`	`Clear`
`.sdp__caption`	`Caption`
`.sdp__select`	—
`.sdp__nav`	`Nav`
`.sdp__weekday`	`Weekday`
`.sdp__footer`	`Footer`
`.sdp__preset`	—
`.sdp__preset--today`	—
`.sdp__today`	—
`.sdp__trigger`	`Trigger`
`.sdp__input`	`Input`
`.sdp__toggle`	`Toggle`
`.sdp__value`	`Value`
`.sdp__value--empty`	—
`.sdp__popup`	`Popup`
`.sdp__calendar`	`Calendar`
`.sdp__day`	`Day`

Token	Layer
`--sdp-accent`	This component
`--sdp-border`	This component
`--sdp-cell`	This component
`--sdp-danger`	This component
`--sdp-font-size`	This component
`--sdp-gap`	This component
`--sdp-hover`	This component
`--sdp-muted`	This component
`--sdp-on-accent`	This component
`--sdp-radius`	This component
`--sdp-surface`	This component
`--sdp-text`	This component
`--ss-accent`	Shared by every component
`--ss-border`	Shared by every component
`--ss-danger`	Shared by every component
`--ss-font-size`	Shared by every component
`--ss-hover`	Shared by every component
`--ss-muted`	Shared by every component
`--ss-on-accent`	Shared by every component
`--ss-radius`	Shared by every component
`--ss-surface`	Shared by every component
`--ss-text`	Shared by every component

Every token switches to its dark value under .dark, [data-theme="dark"], on the page or on any element around the component.

Theming covers the tokens and the ready-made themes.