Date Picker

An input paired with a calendar for picking a date, a range, or a time.

MMDDYYYY

Usage

import { DatePicker } from '@appica/ui-react/date-picker'

<DatePicker mode="single" value={date} onValueChange={setDate} />

DatePicker combines a typeable DateField (and optional TimeField) with a Calendar in a Popover — so a value can be typed or picked. It's a custom composition, not a Base UI primitive. The value shape follows mode: a Date for single, a DateRange ({ from, to }) for range, and Date[] for multiple. Leave value/onValueChange off for an uncontrolled picker.

Examples

Single date

mode="single" (the default) with a Date value. Picking a day closes the popover.

06232026

'use client'

import * as React from 'react'
import { DatePicker } from '@appica/ui-react/date-picker'

export default function DatePickerSingle() {
  const [date, setDate] = React.useState<Date | undefined>(new Date(2026, 5, 23))

  return <DatePicker className="max-w-50" mode="single" value={date} onValueChange={setDate} />
}

Date & time

Add showTime to pair a TimeField with the date so the value carries hours and minutes. Use timeFormat to switch to 12-hour or drop seconds.

06232026

093000

'use client'

import * as React from 'react'
import { DatePicker } from '@appica/ui-react/date-picker'

export default function DatePickerWithTime() {
  const [date, setDate] = React.useState<Date | undefined>(new Date(2026, 5, 23, 9, 30, 0))

  return <DatePicker className="max-w-60" mode="single" showTime value={date} onValueChange={setDate} />
}

Date range

mode="range" selects a span between two dates; the value is a DateRange.

06102026

06162026

'use client'

import * as React from 'react'
import { DatePicker, type DateRange } from '@appica/ui-react/date-picker'

export default function DatePickerRange() {
  const [range, setRange] = React.useState<DateRange | undefined>({
    from: new Date(2026, 5, 10),
    to: new Date(2026, 5, 16),
  })

  return <DatePicker className="max-w-68" mode="range" value={range} onValueChange={setRange} />
}

Multiple dates

mode="multiple" collects an array of dates into a read-only summary field. Add clearable to reset, and formatValue to customize the summary text.

'use client'

import * as React from 'react'
import { DatePicker } from '@appica/ui-react/date-picker'

export default function DatePickerMultiple() {
  const [days, setDays] = React.useState<Date[] | undefined>([
    new Date(2026, 5, 10),
    new Date(2026, 5, 15),
    new Date(2026, 5, 22),
  ])

  return (
    <DatePicker
      className="max-w-60"
      mode="multiple"
      clearable
      value={days}
      onValueChange={setDays}
      placeholder="Pick dates"
    />
  )
}

Disabled dates

disabledDates takes any react-day-picker Matcher (or an array of them) — block past dates, weekends, specific days, or a predicate.

MMDDYYYY

'use client'

import * as React from 'react'
import { DatePicker } from '@appica/ui-react/date-picker'

export default function DatePickerDisabledDates() {
  const [date, setDate] = React.useState<Date | undefined>()

  return (
    <DatePicker
      className="max-w-50"
      mode="single"
      value={date}
      onValueChange={setDate}
      disabledDates={[{ before: new Date() }, { dayOfWeek: [0, 6] }]}
    />
  )
}

Variants

06232026

import { DatePicker } from '@appica/ui-react/date-picker'

const variants = ['outline', 'soft'] as const

export default function DatePickerVariants() {
  return (
    <div className="flex max-w-50 flex-wrap items-center gap-4">
      {variants.map((variant) => (
        <DatePicker key={variant} mode="single" variant={variant} defaultValue={new Date(2026, 5, 23)} />
      ))}
    </div>
  )
}

Sizes

06232026

import { DatePicker } from '@appica/ui-react/date-picker'

const sizes = ['sm', 'md', 'lg'] as const

export default function DatePickerSizes() {
  return (
    <div className="flex max-w-50 flex-wrap items-center gap-4">
      {sizes.map((size) => (
        <DatePicker key={size} mode="single" size={size} defaultValue={new Date(2026, 5, 23)} />
      ))}
    </div>
  )
}

Disabled & error states

disabled blocks the whole control; aria-invalid drives the data-invalid error styling and flags the field for assistive tech. The picker also inherits disabled and the error state from a surrounding Field, so wrapping it in a Field marked invalid produces the same styling and is the better choice when you're also rendering a validation message.

06232026

import { DatePicker } from '@appica/ui-react/date-picker'

export default function DatePickerStates() {
  return (
    <div className="flex w-full max-w-50 flex-col gap-4">
      <DatePicker defaultValue={new Date(2026, 5, 23)} disabled />
      <DatePicker defaultValue={new Date(2026, 5, 23)} aria-invalid />
    </div>
  )
}

RTL

Every Appica UI component supports right-to-left layouts out of the box. Set the dir attribute on a container (commonly your <html> element) so CSS logical properties resolve correctly, and wrap your tree in DirectionProvider so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}

For setup details and caveats, see the RTL guide.

تاريخ الموعد

MMDDYYYY

API reference

Value

Prop	Type	Default	Description
`mode`	`'single' \| 'range' \| 'multiple'`	`'single'`	Selection behavior; determines the `value` shape.
`value`	`Date \| DateRange \| Date[]`	—	Controlled value; shape matches `mode`. Pair with `onValueChange`.
`defaultValue`	`Date \| DateRange \| Date[]`	—	Uncontrolled initial value.
`onValueChange`	`(value) => void`	—	Fires when the selection changes; the argument shape matches `mode`.

Display

Prop	Type	Default	Description
`variant`	`'outline' \| 'soft'`	`'outline'`	Field appearance — bordered or filled.
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Height, padding, and calendar cell scale.
`showTime`	`boolean`	`false`	Add a `TimeField` (single/range modes).
`dateFormat`	`string`	`'MM/dd/yyyy'`	date-fns format for the date field(s).
`timeFormat`	`string`	`'HH:mm:ss'`	date-fns format for the time field(s).
`placeholder`	`string`	—	Placeholder for the multiple-mode summary field.
`clearable`	`boolean`	`false`	Show a clear button (multiple mode).
`formatValue`	`(value: Date[] \| undefined) => string`	—	Customize the multiple-mode summary text.
`rangeSeparator`	`ReactNode`	`'–'`	Separator between the range's two fields.
`startSlot` / `endSlot`	`ReactNode`	—	Adornments rendered inside the field frame.
`triggerIcon`	`ReactNode`	calendar icon	Icon for the popover trigger button.
`triggerAriaLabel`	`string`	`'Open calendar'`	Accessible label for the trigger button.
`className`	`string`	—	Classes on the root wrapper — use for footprint/layout (e.g. `max-w-60`). Merged via `tailwind-merge`.
`inputClassName`	`string`	—	Classes on the inner field box — use to override field styling (border, radius, background). Merged via `tailwind-merge`.

Behavior & state

Prop	Type	Default	Description
`disabled`	`boolean`	`false`	Disable the whole control.
`disabledDates`	`Matcher \| Matcher[]`	—	Dates that can't be selected in the calendar.
`readOnly`	`boolean`	`false`	Make the typeable fields read-only.
`required`	`boolean`	`false`	Mark the form field as required.
`name`	`string`	—	Hidden input name for form submission. `range` mode emits `name[from]` / `name[to]`; with `showTime` the value is a full datetime.
`aria-invalid`	`boolean`	—	Flag the field invalid — sets `data-invalid` for styling + conveys it to assistive tech.
`closeOnSelect`	`boolean`	auto	Override auto-close. By default only single mode closes on pick; range and multiple stay open (dismiss on outside-click/Escape).

Prop	Type	Default	Description
`open`	`boolean`	—	Controlled open state. Pair with `onOpenChange`.
`defaultOpen`	`boolean`	`false`	Uncontrolled initial open state.
`onOpenChange`	`(open: boolean) => void`	—	Fires when the popover opens or closes.
`side`	`'top' \| 'bottom' \| 'left' \| 'right'`	`'bottom'`	Preferred popover side.
`align`	`'start' \| 'center' \| 'end'`	`'end'`	Popover alignment.
`sideOffset`	`number`	`6`	Gap between the field and the popover.
`popoverProps`	`Partial<PopoverContentProps>`	—	Escape hatch forwarded to the inner `PopoverContent` (collision props, `className`, …).

DatePicker also forwards Calendar configuration props — captionLayout, numberOfMonths, weekStartsOn, showOutsideDays, startMonth/endMonth, and more — to the calendar inside the popover.

Accessibility

The date/time portions are typeable segmented fields (role="spinbutton" per segment); the calendar is a role="grid" opened from a labelled trigger button (triggerAriaLabel).
The popover traps focus and restores it to the trigger on close; Escape closes it.
A value can be entered entirely from the keyboard via the fields, or chosen in the calendar with arrow keys — see DateField and Calendar.
disabled blocks the whole control; disabledDates prevents specific days from being chosen.
The error styling is driven by data-invalid; setting aria-invalid flags the field invalid (sets data-invalid) and conveys it to assistive tech. Pass name to submit the value through a hidden input.

Actions & Inputs

Data Display

Decoration & Effects

Layout

Menus

Navigation

Overlays

Status & Feedback

Date Picker

Usage

Examples

Single date

Date & time

Date range

Multiple dates

Disabled dates

Variants

Sizes

Disabled & error states

RTL

API reference

Value

Display

Behavior & state

Popover

Accessibility