Skip to content

DatePicker

A date picker: a segmented date field with a calendar that opens from a trigger. Render DatePicker.Field with a DatePicker.Trigger inside it, and DatePicker.Content holding a DatePicker.Calendar. Inside a Field it takes disabled and required from there.

The value is a DateValue from @internationalized/date, such as new CalendarDate(2026, 3, 10) or parseDate('2026-03-10').

Built on bits-ui DatePicker.

<DatePicker bind:value>
<DatePicker.Field>
<DatePicker.Trigger />
</DatePicker.Field>
<DatePicker.Content>
<DatePicker.Calendar />
</DatePicker.Content>
</DatePicker>
mmddyyyy

value: none

  • Composed from parts, so the field, its trigger, and the calendar are yours to arrange.
  • One value, bindable. open is bindable too. min and max bound the selectable dates.
  • granularity sets the smallest unit the field edits, from day down to second.
  • DatePicker.Field takes state from an enclosing Field, or directly. error and warn share the input component class with Input.
  • The calendar floats in a portal, positioned to the field.
  • While the calendar is open, the field shows the darker border-gray-9 frame, as Select.Trigger does.

Every part is a property on DatePicker. Field is the segmented input and holds the Trigger button that opens the calendar. Content is the floating panel, portaled to the body, and holds the Calendar.

<DatePicker>
<DatePicker.Field>
<DatePicker.Trigger />
</DatePicker.Field>
<DatePicker.Content>
<DatePicker.Calendar />
</DatePicker.Content>
</DatePicker>

bind:value on the root. The value is a DateValue from @internationalized/date, or undefined until one is picked. value?.toString() prints it as ISO YYYY-MM-DD.

mmddyyyy

value: none

Code
TwoWay.svelte
<script lang="ts">
import type { ComponentProps } from "svelte";
import { DatePicker, Field, Label } from "@viamrobotics/prime-ui";
let value = $state<ComponentProps<typeof DatePicker>["value"]>();
</script>
<div class="not-content">
<Field class="flex max-w-xs flex-col gap-1">
<Label>Deploy date</Label>
<DatePicker bind:value name="deploy">
<DatePicker.Field>
<DatePicker.Trigger />
</DatePicker.Field>
<DatePicker.Content>
<DatePicker.Calendar />
</DatePicker.Content>
</DatePicker>
</Field>
<p class="mt-3 text-sm text-subtle-2">value: <code>{value?.toString() ?? "none"}</code></p>
</div>

Pass bind:value a getter and a setter. State & binding explains both modes.

mmddyyyy

Days after the 28th are declined by the setter, so picking one changes nothing.

value: none

Code
Controlled.svelte
<script lang="ts">
import type { ComponentProps } from "svelte";
import { DatePicker, Field, Hint, Label } from "@viamrobotics/prime-ui";
let value = $state<ComponentProps<typeof DatePicker>["value"]>();
</script>
<div class="not-content">
<Field class="flex max-w-xs flex-col gap-1">
<Label>Billing day</Label>
<DatePicker
bind:value={
() => value,
(next) => {
if (!next || next.day <= 28) value = next;
}
}
>
<DatePicker.Field>
<DatePicker.Trigger />
</DatePicker.Field>
<DatePicker.Content>
<DatePicker.Calendar />
</DatePicker.Content>
</DatePicker>
<Hint>Days after the 28th are declined by the setter, so picking one changes nothing.</Hint>
</Field>
<p class="mt-3 text-sm text-subtle-2">value: <code>{value?.toString() ?? "none"}</code></p>
</div>

min and max take date objects from @internationalized/date, such as new CalendarDate(2026, 1, 1). Dates outside the range cannot be selected in the calendar. A date typed outside the range marks the field aria-invalid and paints the same error border as state="error".

DatePicker.Trigger takes aria-label, which defaults to “Open calendar”. DatePicker.Content takes aria-label, which defaults to “Choose a date”. DatePicker.Calendar takes aria-label too. It replaces “Choose a date” at the start of the calendar grid’s name, and the month and year stay appended. Set all three to name them on a page that is not in English.

The previous and next month buttons take their names from the root locale through Intl.RelativeTimeFormat, such as “Last month” and “Next month” in en-US. They need no override.

<DatePicker locale="de-DE">
<DatePicker.Field>
<DatePicker.Trigger aria-label="Kalender öffnen" />
</DatePicker.Field>
<DatePicker.Content aria-label="Datum auswählen">
<DatePicker.Calendar aria-label="Datum auswählen" />
</DatePicker.Content>
</DatePicker>

DatePicker.Content takes side and align to place the calendar, and sideOffset and alignOffset to nudge it. It opens below the field and aligns to its end by default. The API table lists each option and its default.

disabled disables the field and its trigger. readonly shows the read-only frame and disables the trigger, so the calendar cannot open and the segments cannot be edited.

Default

mmddyyyy

In a field, with label and hint

mmddyyyy

The first day of the billing period.

Error

mmddyyyy

Pick a start date.

Warn

mmddyyyy

This date is in the past.

Disabled

mmddyyyy

Read only

mmddyyyy

Minute granularity

mmddyyyy––––AM

DatePicker.Field, DatePicker.Trigger, and DatePicker.Calendar take class on the element they render. DatePicker takes no class, since it renders no element of its own. DatePicker.Trigger takes button attributes, and its children replace the calendar icon. DatePicker.Content wears z-popover. See z layers.

With focus on a segment of the field:

KeyAction
DigitsTypes into the segment.
ArrowUp / ArrowDownSteps the segment up or down.
ArrowLeft / ArrowRightMoves to the previous or next segment.

With focus on a day in the open calendar:

KeyAction
ArrowLeft / ArrowRightMoves to the previous or next day.
ArrowUp / ArrowDownMoves to the same day a week earlier or later.
Enter / SpaceSelects the focused day.
EscapeCloses the calendar.
PropTypeDefaultDescription
bind:valueDateValueThe selected date. Two-way bindable.
bind:openbooleanWhether the calendar is open. Two-way bindable.
minDateValueThe earliest selectable date.
maxDateValueThe latest selectable date.
granularity'day' | 'hour' | 'minute' | 'second''day'The smallest unit the field edits.
localestring'en-US'BCP 47 locale for segment order, month names, and the names of the calendar's month buttons.
namestringName for form submission.
disabledbooleanDisable the picker. Defaults to the enclosing field's disabled.
requiredbooleanMake a date required. Defaults to the enclosing field's required.
readonlybooleanfalseMake the field read-only.
childrenSnippetThe DatePicker.* parts.

DatePicker.Calendar

The month calendar of a DatePicker: a header with the previous and next month buttons around the month heading, the weekday names, and the day grid. Render it inside DatePicker.Content.

Arrow keys move between days, and Enter or Space selects the focused day. The header buttons change the month, and their names (“Last month” and “Next month” in en-US) follow the picker’s locale. The calendar’s accessible name is its aria-label followed by the month on show.

<DatePicker.Content>
<DatePicker.Calendar aria-label="Choose a start date" />
</DatePicker.Content>

Takes extraClasses, 'aria-label': label, ...restProps }: Props as its props.

DatePicker.Content

The floating panel of a DatePicker, portaled to the body. Render a DatePicker.Calendar inside it.

PropTypeDefaultDescription
idstringElement id. null is not accepted.
dir'ltr' | 'rtl'Text direction of the panel. auto is not accepted, because positioning needs a concrete direction.
side'top' | 'right' | 'bottom' | 'left''bottom'Which side of the trigger the panel opens on.
align'start' | 'center' | 'end''end'Alignment of the panel along the trigger's edge.
sideOffsetnumber4Gap in pixels between the trigger and the panel.
alignOffsetnumber0Shift in pixels along the alignment axis.
portalPortalTargettrueWhere the panel renders: true at the end of <body>, false in place, or inside an element or the first match of a CSS selector.

Plus everything in HTMLAttributes<HTMLDivElement>, spread onto the element.

DatePicker.Field

The segmented date field of a DatePicker. Each part of the date is its own editable segment: type digits, or press the arrow keys to step it. Place a DatePicker.Trigger inside it to open the calendar.

Inside a Field it takes its id (the field’s controlId), state, aria-labelledby, and aria-describedby from there. An error state, or a typed date outside the picker’s min and max, sets aria-invalid and the error border, and warn the warning border, through the same input class an Input wears. The border darkens while the calendar is open, as a Select.Trigger does while its list is open.

<DatePicker.Field>
<DatePicker.Trigger />
</DatePicker.Field>
PropTypeDefaultDescription
idstringElement id. null is not accepted.
stateFieldStateContextual state. Defaults to the enclosing field's state.

Plus everything in HTMLAttributes<HTMLDivElement>, spread onto the element.

DatePicker.Trigger

The button that opens the calendar of a DatePicker. Place it inside DatePicker.Field, after the segments. It shows a calendar icon, and children replace the icon.

<DatePicker.Field>
<DatePicker.Trigger aria-label="Pick a start date" />
</DatePicker.Field>
PropTypeDefaultDescription
idstringElement id. null is not accepted.
disabledbooleanDisable the button. Defaults to on when the enclosing date picker is disabled or readonly, so a read-only picker cannot open its calendar.

Plus everything in HTMLButtonAttributes, spread onto the element.