structyl

Date Picker API

View component

The full prop reference for the Date Picker component. A calendar inside a popover for picking a date.

Import

tsx
import { DatePicker } from '@structyl/styled';

Props

DatePicker (main)

A styled date picker component with label, helper text, and integrated trigger/content. The default export, suitable for most use cases.

PropTypeDefault
value#Date | null

Controlled selected date value

—
defaultValue#Date | null

Default date when uncontrolled

—
onChange#(date: Date | null, context: PickerChangeContext<DateValidationError>) => void

Callback when date value changes

—
onValueChange#(date: Date | undefined) => void

Simplified callback when date value changes

—
onAccept#(date: Date | null, context: PickerChangeContext<DateValidationError>) => void

Callback when a date is accepted/committed

—
onError#(error: DateValidationError | null, value: Date | null) => void

Callback when validation error occurs

—
open#boolean

Controlled popover open state

—
defaultOpen#boolean

Default open state when uncontrolled

—
onOpenChange#(open: boolean) => void

Callback when open state changes

—
onOpen#() => void

Callback when popover opens

—
onClose#() => void

Callback when popover closes

—
closeOnSelect#boolean

Close popover immediately after selecting a date

true
disabled#boolean

Disable all date picker interactions

—
readOnly#boolean

Prevent value changes (read-only mode)

—
minDate#Date

Minimum selectable date

—
maxDate#Date

Maximum selectable date

—
disablePast#boolean

Disable all dates before today

—
disableFuture#boolean

Disable all dates after today

—
disabledDays#(date: Date) => boolean

Predicate function to disable specific dates

—
shouldDisableDate#(date: Date) => boolean

Predicate function to disable specific dates (alias for disabledDays)

—
shouldDisableMonth#(date: Date) => boolean

Predicate function to disable specific months

—
shouldDisableYear#(date: Date) => boolean

Predicate function to disable specific years

—
weekStartsOn#number

Starting day of the week (0=Sunday, 1=Monday, etc.)

0
locale#string

Locale for date formatting and localization

—
autoFocus#boolean

Auto-focus the trigger on mount

—
dayOfWeekFormatter#(date: Date) => string

Custom formatter for day-of-week headers

—
disableHighlightToday#boolean

Disable visual highlight of today's date

—
disableOpenPicker#boolean

Disable opening the date picker (trigger becomes non-interactive)

—
displayWeekNumber#boolean

Show week numbers in the calendar

—
fixedWeekNumber#number

Fixed number of weeks to display per month

—
format#Intl.DateTimeFormatOptions | string

Date format for display (Intl options or pattern like 'MM/DD/YYYY')

{ dateStyle: 'medium' }
formatDensity#'dense' | 'spacious'

Spacing density for formatted date output

'dense'
loading#boolean

Show loading state in popover

—
renderLoading#() => React.ReactNode

Custom loading indicator render function

—
showDaysOutsideCurrentMonth#boolean

Display days from adjacent months in calendar grid

—
label#React.ReactNode

Label text displayed above the trigger

—
helperText#React.ReactNode

Helper text displayed below the trigger

—
placeholder#React.ReactNode

Placeholder text when no date is selected

'MM/DD/YYYY'
id#string

HTML id attribute for the trigger element

—
name#string

HTML name attribute for the trigger element

—
required#boolean

Mark the label with a required indicator

—
error#boolean

Mark helper text and trigger as errored

—
showOutsideDays#boolean

Alias for showDaysOutsideCurrentMonth

—
className#string

CSS class for the root wrapper

—
triggerClassName#string

CSS class for the trigger button

—
contentClassName#string

CSS class for the popover content

—
calendarClassName#string

CSS class for the calendar component

—
rootProps#React.ComponentPropsWithoutRef<'div'>

Native HTML props forwarded to root wrapper div (onClick, style, role, data-*, aria-*)

—

DatePicker.Root

The root provider component for date picker context and popover state management. Used for building custom layouts.

PropTypeDefault
children#React.ReactNode

Child components (Trigger, Content, etc.)

—
value#Date | null

Controlled selected date

—
defaultValue#Date | null

Default date when uncontrolled

—
onChange#(date: Date | null, context: PickerChangeContext<DateValidationError>) => void

Called when date changes

—
onValueChange#(date: Date | undefined) => void

Simplified date change callback

—
onAccept#(date: Date | null, context: PickerChangeContext<DateValidationError>) => void

Called when date is accepted

—
onError#(error: DateValidationError | null, value: Date | null) => void

Called on validation error

—
open#boolean

Controlled popover open state

—
defaultOpen#boolean

Default popover open state

—
onOpenChange#(open: boolean) => void

Called when popover open state changes

—
onOpen#() => void

Called when popover opens

—
onClose#() => void

Called when popover closes

—
closeOnSelect#boolean

Auto-close popover after date selection

true
disabled#boolean

Disable interactions

—
readOnly#boolean

Read-only mode

—
minDate#Date

Minimum selectable date

—
maxDate#Date

Maximum selectable date

—
disablePast#boolean

Disable past dates

—
disableFuture#boolean

Disable future dates

—
disabledDays#(date: Date) => boolean

Predicate to disable specific dates

—
shouldDisableDate#(date: Date) => boolean

Predicate to disable specific dates

—
shouldDisableMonth#(date: Date) => boolean

Predicate to disable specific months

—
shouldDisableYear#(date: Date) => boolean

Predicate to disable specific years

—
weekStartsOn#number

First day of week (0=Sunday, 1=Monday, etc.)

0
locale#string

Locale for formatting

—
autoFocus#boolean

Auto-focus trigger

—
dayOfWeekFormatter#(date: Date) => string

Custom day-of-week formatter

—
desktopModeMediaQuery#string

Media query for desktop mode detection

—
disableHighlightToday#boolean

Don't highlight today

—
disableOpenPicker#boolean

Disable opening picker

—
displayWeekNumber#boolean

Show week numbers

—
fixedWeekNumber#number

Fixed weeks per month

—
format#Intl.DateTimeFormatOptions | string

Date format specification

—
formatDensity#'dense' | 'spacious'

Format spacing

—
inputRef#React.Ref<HTMLInputElement>

Ref to underlying input element

—
keepOpenDuringFieldFocus#boolean

Keep popover open when field is focused

—
label#React.ReactNode

Label node

—
loading#boolean

Show loading state

—
localeText#PickerLocaleText

Localized text overrides (Record<string, React.ReactNode>)

—
monthsPerRow#3 | 4

Months to display per row in month view

—
name#string

Form input name

—
onMonthChange#(month: Date) => void

Called when displayed month changes

—
onSelectedSectionsChange#(newValue: PickerSelectedSections) => void

Called when selected field section changes

—
onViewChange#(view: DatePickerView) => void

Called when view changes (day/month/year)

—
onYearChange#(year: Date) => void

Called when displayed year changes

—
openTo#'day' | 'month' | 'year'

Initial view when opened

'day'
orientation#'landscape' | 'portrait'

Picker layout orientation

—
reduceAnimations#boolean

Disable animations

—
referenceDate#Date

Reference date for calculations

—
renderLoading#() => React.ReactNode

Custom loading render function

—
selectedSections#PickerSelectedSections

Controlled selected field section

—
defaultSelectedSections#PickerSelectedSections

Default selected field section

—
showDaysOutsideCurrentMonth#boolean

Show adjacent month days

—
slotProps#PickerSlotProps

Slot component props (Record<string, unknown>)

—
slots#PickerSlots

Slot component overrides (Record<string, React.ElementType>)

—
sx#PickerSx

System prop styles

—
timezone#string

Timezone for date operations

—
view#'day' | 'month' | 'year'

Controlled current view

—
defaultView#'day' | 'month' | 'year'

Default initial view

—
viewRenderers#Partial<Record<DatePickerView, DatePickerViewRenderer | null>>

Custom renderers per view (day/month/year)

—
views#('day' | 'month' | 'year')[]

Array of enabled views

—
yearsOrder#'asc' | 'desc'

Year list sort order

—
yearsPerRow#3 | 4

Years to display per row in year view

—

DatePicker.Trigger

The button that opens the date picker popover. Inherits from Popover.Trigger.

PropTypeDefault
asChild#boolean

Render as child element instead of button

—
className#string

CSS class

—
disabled#boolean

Disable the trigger button

—
children#React.ReactNode

Trigger content

—
onClick#(event: React.MouseEvent<HTMLButtonElement>) => void

Click handler

—
Standard HTML button attributes#various

aria-*, data-*, role, tabIndex, style, etc.

—

DatePicker.Content

The popover content wrapper containing the calendar. Inherits from Popover.Content with additional date picker props.

PropTypeDefault
align#'start' | 'center' | 'end'

Alignment relative to trigger

'center'
side#'top' | 'right' | 'bottom' | 'left'

Position relative to trigger

—
sideOffset#number

Distance from trigger

6
alignOffset#number

Alignment offset

—
arrowPadding#number

Arrow padding from edges

—
avoidCollisions#boolean

Auto-adjust position to avoid collisions

—
collisionBoundary#Element | Element[] | null

Collision detection boundary

—
collisionPadding#number

Padding for collision detection

—
strategy#'fixed' | 'absolute'

Positioning strategy

—
sticky#'partial' | 'always'

Sticky behavior

—
hideWhenDetached#boolean

Hide when trigger is off-screen

—
updatePositionStrategy#'always' | 'optimized'

Position update frequency

—
asChild#boolean

Render as child element

—
forceMount#boolean

Force mount in DOM (even when closed)

—
onOpenAutoFocus#(event: Event) => void

Focus trap on open

—
onCloseAutoFocus#(event: Event) => void

Focus return on close

—
onEscapeKeyDown#(event: KeyboardEvent) => void

Escape key handler

—
onPointerDownOutside#(event: PointerDownOutsideEvent) => void

Pointer down outside handler

—
onFocusOutside#(event: FocusOutsideEvent) => void

Focus outside handler

—
onInteractOutside#(event: PointerDownOutsideEvent | FocusOutsideEvent) => void

Generic outside interaction handler

—
className#string

CSS class

—
calendarClassName#string

CSS class for inner calendar

—
loading#boolean

Show loading indicator

—
showOutsideDays#boolean

Display adjacent month days

—
showDaysOutsideCurrentMonth#boolean

Display adjacent month days (alias)

—
Standard HTML div attributes#various

style, data-*, role, aria-*, etc.

—

DatePicker.Calendar

The calendar grid component. Inherits from Calendar.Root with date picker context integration.

PropTypeDefault
minDate#Date

Minimum selectable date

—
maxDate#Date

Maximum selectable date

—
disablePast#boolean

Disable past dates

—
disableFuture#boolean

Disable future dates

—
disabled#boolean

Disable calendar

—
disabledDays#(date: Date) => boolean

Disable predicate for dates

—
shouldDisableDate#(date: Date) => boolean

Disable predicate for dates

—
shouldDisableMonth#(date: Date) => boolean

Disable predicate for months

—
shouldDisableYear#(date: Date) => boolean

Disable predicate for years

—
weekStartsOn#number

First day of week

0
locale#string

Locale for formatting

—
disableHighlightToday#boolean

Don't highlight today

—
displayWeekNumber#boolean

Show week numbers

—
fixedWeekNumber#number

Fixed weeks per month

—
showDaysOutsideCurrentMonth#boolean

Show adjacent month days

—
dayOfWeekFormatter#(date: Date) => string

Custom day-of-week formatter

—
onMonthChange#(month: Date) => void

Month change callback

—
onYearChange#(year: Date) => void

Year change callback

—
className#string

CSS class

—
showOutsideDays#boolean

Show adjacent month days (alias)

—
Standard HTML div attributes#various

style, data-*, role, aria-*, etc.

—

DatePicker.Value

A text component that displays the formatted selected date or a placeholder.

PropTypeDefault
format#Intl.DateTimeFormatOptions | string

Date format (Intl options or pattern string)

{ dateStyle: 'medium' }
formatDensity#'dense' | 'spacious'

Spacing for formatted output

'dense'
locale#string

Locale for formatting

—
placeholder#React.ReactNode

Text when no date is selected

'Pick a date'

DatePicker.Loading

A component that displays a loading indicator or custom loading content.

PropTypeDefault
No props#none

Uses context renderLoading or localeText.loading from DatePicker.Root

—

Source code

If you didn't find what you need here, read the component implementation .

structyl — Accessible React Component Library