Date Picker

A component for selecting a date from a calendar interface.

Label

Anatomy

Usage

<script>
  import {DatePicker} from 'ui-ingredients';
  import {CalendarIcon, ChevronLeftIcon, ChevronRightIcon} from '$lib/icons';

  /** @type {import('ui-ingredients').DateValue[]} */
  let value = $state([DatePicker.parse('1990-01-01')]);
</script>

<DatePicker.Root
  {value}
  onValueChange={(detail) => {
    value = detail.value;
  }}
>
  {#snippet children(context)}
    <DatePicker.Label>Label</DatePicker.Label>
    <DatePicker.Control>
      <DatePicker.Input />
      <DatePicker.Trigger>
        <CalendarIcon />
      </DatePicker.Trigger>
    </DatePicker.Control>

    <DatePicker.Positioner>
      <DatePicker.Content>
        <DatePicker.View view="day">
          <DatePicker.ViewControl>
            <DatePicker.PrevTrigger>
              <ChevronLeftIcon />
            </DatePicker.PrevTrigger>
            <DatePicker.ViewTrigger>
              <DatePicker.RangeText />
            </DatePicker.ViewTrigger>
            <DatePicker.NextTrigger>
              <ChevronRightIcon />
            </DatePicker.NextTrigger>
          </DatePicker.ViewControl>

          <DatePicker.Table>
            <DatePicker.TableHead>
              <DatePicker.TableRow>
                {#each context.weekDays as weekDay}
                  <DatePicker.TableHeader>
                    {weekDay.narrow}
                  </DatePicker.TableHeader>
                {/each}
              </DatePicker.TableRow>
            </DatePicker.TableHead>

            <DatePicker.TableBody>
              {#each context.weeks as week}
                <DatePicker.TableRow>
                  {#each week as day}
                    <DatePicker.DayTableCell value={day}>
                      <DatePicker.DayTableCellTrigger>
                        {day.day}
                      </DatePicker.DayTableCellTrigger>
                    </DatePicker.DayTableCell>
                  {/each}
                </DatePicker.TableRow>
              {/each}
            </DatePicker.TableBody>
          </DatePicker.Table>
        </DatePicker.View>

        <!-- MONTH -->
        <DatePicker.View view="month">
          <DatePicker.ViewControl>
            <DatePicker.PrevTrigger>
              <ChevronLeftIcon />
            </DatePicker.PrevTrigger>
            <DatePicker.ViewTrigger>
              <DatePicker.RangeText />
            </DatePicker.ViewTrigger>
            <DatePicker.NextTrigger>
              <ChevronRightIcon />
            </DatePicker.NextTrigger>
          </DatePicker.ViewControl>

          <DatePicker.Table>
            <DatePicker.TableBody>
              {#each context.getMonthsGrid( {columns: 4, format: 'short'}, ) as months}
                <DatePicker.TableRow>
                  {#each months as month}
                    <DatePicker.MonthTableCell value={month.value}>
                      <DatePicker.MonthTableCellTrigger>
                        {month.label}
                      </DatePicker.MonthTableCellTrigger>
                    </DatePicker.MonthTableCell>
                  {/each}
                </DatePicker.TableRow>
              {/each}
            </DatePicker.TableBody>
          </DatePicker.Table>
        </DatePicker.View>

        <!-- YEAR -->
        <DatePicker.View view="year">
          <DatePicker.ViewControl>
            <DatePicker.PrevTrigger>
              <ChevronLeftIcon />
            </DatePicker.PrevTrigger>
            <DatePicker.ViewTrigger>
              <DatePicker.RangeText />
            </DatePicker.ViewTrigger>
            <DatePicker.NextTrigger>
              <ChevronRightIcon />
            </DatePicker.NextTrigger>
          </DatePicker.ViewControl>

          <DatePicker.Table>
            <DatePicker.TableBody>
              {#each context.getYearsGrid({columns: 4}) as years}
                <DatePicker.TableRow>
                  {#each years as year}
                    <DatePicker.YearTableCell value={year.value}>
                      <DatePicker.YearTableCellTrigger>
                        {year.label}
                      </DatePicker.YearTableCellTrigger>
                    </DatePicker.YearTableCell>
                  {/each}
                </DatePicker.TableRow>
              {/each}
            </DatePicker.TableBody>
          </DatePicker.Table>
        </DatePicker.View>
      </DatePicker.Content>
    </DatePicker.Positioner>
  {/snippet}
</DatePicker.Root>

Range Date Picker

<script>
  import {DatePicker} from 'ui-ingredients';
  import {
    CalendarIcon,
    ChevronLeftIcon,
    ChevronRightIcon,
    XCloseIcon,
  } from '$lib/icons';
</script>

<DatePicker.Root fixedWeeks selectionMode="range">
  {#snippet children(context)}
    <DatePicker.Label>Label</DatePicker.Label>
    <DatePicker.Control>
      <DatePicker.Input index={0} />
      <DatePicker.Input index={1} />
      <DatePicker.ClearTrigger>
        <XCloseIcon />
      </DatePicker.ClearTrigger>
      <DatePicker.Trigger>
        <CalendarIcon />
      </DatePicker.Trigger>
    </DatePicker.Control>

    <DatePicker.Positioner>
      <DatePicker.Content>
        <DatePicker.View view="day">
          <DatePicker.ViewControl>
            <DatePicker.PrevTrigger>
              <ChevronLeftIcon />
            </DatePicker.PrevTrigger>
            <DatePicker.ViewTrigger>
              <DatePicker.RangeText />
            </DatePicker.ViewTrigger>
            <DatePicker.NextTrigger>
              <ChevronRightIcon />
            </DatePicker.NextTrigger>
          </DatePicker.ViewControl>

          <DatePicker.Table>
            <DatePicker.TableHead>
              <DatePicker.TableRow>
                {#each context.weekDays as weekDay}
                  <DatePicker.TableHeader>
                    {weekDay.narrow}
                  </DatePicker.TableHeader>
                {/each}
              </DatePicker.TableRow>
            </DatePicker.TableHead>

            <DatePicker.TableBody>
              {#each context.weeks as week}
                <DatePicker.TableRow>
                  {#each week as day}
                    <DatePicker.DayTableCell value={day}>
                      <DatePicker.DayTableCellTrigger>
                        {day.day}
                      </DatePicker.DayTableCellTrigger>
                    </DatePicker.DayTableCell>
                  {/each}
                </DatePicker.TableRow>
              {/each}
            </DatePicker.TableBody>
          </DatePicker.Table>
        </DatePicker.View>

        <!-- MONTH -->
        <DatePicker.View view="month">
          <DatePicker.ViewControl>
            <DatePicker.PrevTrigger>
              <ChevronLeftIcon />
            </DatePicker.PrevTrigger>

            <DatePicker.ViewTrigger>
              <DatePicker.RangeText />
            </DatePicker.ViewTrigger>

            <DatePicker.NextTrigger>
              <ChevronRightIcon />
            </DatePicker.NextTrigger>
          </DatePicker.ViewControl>

          <DatePicker.Table>
            <DatePicker.TableBody>
              {#each context.getMonthsGrid( {columns: 4, format: 'short'}, ) as months}
                <DatePicker.TableRow>
                  {#each months as month}
                    <DatePicker.MonthTableCell value={month.value}>
                      <DatePicker.MonthTableCellTrigger>
                        {month.label}
                      </DatePicker.MonthTableCellTrigger>
                    </DatePicker.MonthTableCell>
                  {/each}
                </DatePicker.TableRow>
              {/each}
            </DatePicker.TableBody>
          </DatePicker.Table>
        </DatePicker.View>

        <!-- YEAR -->
        <DatePicker.View view="year">
          <DatePicker.ViewControl>
            <DatePicker.PrevTrigger>
              <ChevronLeftIcon />
            </DatePicker.PrevTrigger>

            <DatePicker.ViewTrigger>
              <DatePicker.RangeText />
            </DatePicker.ViewTrigger>

            <DatePicker.NextTrigger>
              <ChevronRightIcon />
            </DatePicker.NextTrigger>
          </DatePicker.ViewControl>

          <DatePicker.Table>
            <DatePicker.TableBody>
              {#each context.getYearsGrid({columns: 4}) as years}
                <DatePicker.TableRow>
                  {#each years as year}
                    <DatePicker.YearTableCell value={year.value}>
                      <DatePicker.YearTableCellTrigger>
                        {year.label}
                      </DatePicker.YearTableCellTrigger>
                    </DatePicker.YearTableCell>
                  {/each}
                </DatePicker.TableRow>
              {/each}
            </DatePicker.TableBody>
          </DatePicker.Table>
        </DatePicker.View>
      </DatePicker.Content>
    </DatePicker.Positioner>
  {/snippet}
</DatePicker.Root>

API Reference

Root

Prop	Default	Description
`closeOnSelect`	`true`	`boolean` Whether the calendar should close after the date selection is complete. This is ignored when the selection mode is `multiple`.
`defaultFocusedValue`		`DateValue` The initial focused date when rendered. Use when you don't need to control the focused date of the date picker.
`defaultOpen`		`boolean` The initial open state of the date picker when rendered. Use when you don't need to control the open state of the date picker.
`defaultValue`		`DateValue[]` The initial selected date(s) when rendered. Use when you don't need to control the selected date(s) of the date picker.
`defaultView`	`"day"`	`DateView` The default view of the calendar
`disabled`		`boolean` Whether the calendar is disabled.
`fixedWeeks`		`boolean` Whether the calendar should have a fixed number of weeks. This renders the calendar with 6 weeks instead of 5 or 6.
`focusedValue`		`DateValue` The controlled focused date.
`format`		`(date: LocaleDetails) => string` The format of the date to display in the input.
`id`		`string` The unique identifier of the machine.
`ids`		`{ root?: string; label(index: number)?: string; table(id: string)?: string; tableHeader(id: string)?: string; tableBody(id: string)?: string; tableRow(id: string)?: string; content?: string; cellTrigger(id: string)?: string; prevTrigger(view: DateView)?: string; clearTrigger: string; control: string; input(index: number)?: string; trigger?: string; monthSelect?: string; yearSelect?: string; positioner?: string; }` The ids of the elements in the date picker. Useful for composition.
`isDateUnavailable`		`(date: DateValue, locale: string) => boolean` Returns whether a date of the calendar is available.
`keepMounted`		`boolean` Whether to keep the component mounted after exit.
`lazyMount`		`boolean` Whether to enable lazy mounting.
`locale`	`"en-US"`	`string` The locale (BCP 47 language tag) to use when formatting the date.
`max`		`DateValue` The maximum date that can be selected.
`maxView`	`"year"`	`DateView` The maximum view of the calendar
`min`		`DateValue` The minimum date that can be selected.
`minView`	`"day"`	`DateView` The minimum view of the calendar
`name`		`string` The `name` attribute of the input element.
`numOfMonths`		`number` The number of months to display.
`onFocusChange`		`(details: FocusChangeDetails) => void` Function called when the focused date changes.
`onOpenChange`		`(details: OpenChangeDetails) => void` Function called when the calendar opens or closes.
`onValueChange`		`(details: ValueChangeDetails) => void` Function called when the value changes.
`onViewChange`		`(details: ViewChangeDetails) => void` Function called when the view changes.
`open`		`boolean` The controlled open state of the date picker
`outsideDaySelectable`	`false`	`boolean` Whether day outside the visible range can be selected.
`parse`		`(value: string, details: LocaleDetails) => DateValue` Function to parse the date from the input back to a DateValue.
`placeholder`		`string` The placeholder text to display in the input.
`positioning`		`PositioningOptions` The user provided options used to position the date picker content
`readOnly`		`boolean` Whether the calendar is read-only.
`selectionMode`	`"single"`	`SelectionMode` The selection mode of the calendar. - `single` - only one date can be selected - `multiple` - multiple dates can be selected - `range` - a range of dates can be selected
`startOfWeek`		`number` The first day of the week. `0` - Sunday `1` - Monday `2` - Tuesday `3` - Wednesday `4` - Thursday `5` - Friday `6` - Saturday
`timeZone`	`"UTC"`	`string` The time zone to use
`translations`		`IntlTranslations` The localized messages to use.
`value`		`DateValue[]` The controlled selected date(s).
`view`		`DateView` The view of the calendar
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-part`	root
`data-readonly`	Present when read-only
`data-scope`	date-picker
`data-state`	"open" \| "closed"

ClearTrigger

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Content

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-part`	content
`data-placement`	The placement of the content
`data-scope`	date-picker
`data-state`	"open" \| "closed"

Control

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-part`	control
`data-scope`	date-picker

Input

Prop	Default	Description
`index`		`number`
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-index`	The index of the item
`data-part`	input
`data-scope`	date-picker
`data-state`	"open" \| "closed"

Label

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-index`	The index of the item
`data-part`	label
`data-readonly`	Present when read-only
`data-scope`	date-picker
`data-state`	"open" \| "closed"

MonthSelect

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

NextTrigger

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-part`	next-trigger
`data-scope`	date-picker

Positioner

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

PresetTrigger

Prop	Default	Description
`value`		`PresetTriggerValue`
`asChild`		`Snippet` Render a different element.

PrevTrigger

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-part`	prev-trigger
`data-scope`	date-picker

RangeText

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Table

Prop	Default	Description
`columns`		`number`
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-columns`
`data-part`	table
`data-scope`	date-picker
`data-view`	The view of the table

TableBody

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-part`	table-body
`data-scope`	date-picker
`data-view`	The view of the tablebody

TableCell

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

TableCellTrigger

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

TableHead

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-part`	table-head
`data-scope`	date-picker
`data-view`	The view of the tablehead

TableHeader

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-part`	table-header
`data-scope`	date-picker
`data-view`	The view of the tableheader

TableRow

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-part`	table-row
`data-scope`	date-picker
`data-view`	The view of the tablerow

Trigger

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-part`	trigger
`data-placement`	The placement of the trigger
`data-scope`	date-picker
`data-state`	"open" \| "closed"

View

Prop	Default	Description
`view`		`DateView`
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-part`	view
`data-scope`	date-picker
`data-view`	The view of the view

ViewControl

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-part`	view-control
`data-scope`	date-picker
`data-view`	The view of the viewcontrol

ViewTrigger

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-part`	view-trigger
`data-scope`	date-picker
`data-view`	The view of the viewtrigger

YearSelect

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Accessibility

Keyboard Support

Key	Description
ArrowLeft	Moves focus to the previous day within the current week.
ArrowRight	Moves focus to the next day within the current week.
ArrowUp	Moves focus to the same day of the week in the previous week.
ArrowDown	Moves focus to the same day of the week in the next week.
Home	Moves focus to the first day of the current month.
End	Moves focus to the last day of the current month.
PageUp	Moves focus to the same day of the month in the previous month.
PageDown	Moves focus to the same day of the month in the next month.
Enter	Selects the focused date and closes the date picker.
Esc	Closes the date picker without selecting any date.