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>value: none
- Composed from parts, so the field, its trigger, and the calendar are yours to arrange.
- One
value, bindable.openis bindable too.minandmaxbound the selectable dates. granularitysets the smallest unit the field edits, fromdaydown tosecond.DatePicker.Fieldtakesstatefrom an enclosingField, or directly.errorandwarnshare theinputcomponent class withInput.- The calendar floats in a portal, positioned to the field.
- While the calendar is open, the field shows the darker
border-gray-9frame, asSelect.Triggerdoes.
Anatomy
Section titled “Anatomy”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>Two-way binding
Section titled “Two-way binding”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.
value: none
Code
<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>Fully controlled
Section titled “Fully controlled”Pass bind:value a getter and a setter. State & binding explains both modes.
Days after the 28th are declined by the setter, so picking one changes nothing.
value: none
Code
<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>Bounds
Section titled “Bounds”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".
Accessible names
Section titled “Accessible names”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>Placement
Section titled “Placement”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.
States
Section titled “States”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
In a field, with label and hint
The first day of the billing period.
Error
Pick a start date.
Warn
This date is in the past.
Disabled
Read only
Minute granularity
Styling
Section titled “Styling”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.
Keyboard
Section titled “Keyboard”With focus on a segment of the field:
| Key | Action |
|---|---|
| Digits | Types into the segment. |
| ArrowUp / ArrowDown | Steps the segment up or down. |
| ArrowLeft / ArrowRight | Moves to the previous or next segment. |
With focus on a day in the open calendar:
| Key | Action |
|---|---|
| ArrowLeft / ArrowRight | Moves to the previous or next day. |
| ArrowUp / ArrowDown | Moves to the same day a week earlier or later. |
| Enter / Space | Selects the focused day. |
| Escape | Closes the calendar. |
| Prop | Type | Default | Description |
|---|---|---|---|
bind:value | DateValue | The selected date. Two-way bindable. | |
bind:open | boolean | Whether the calendar is open. Two-way bindable. | |
min | DateValue | The earliest selectable date. | |
max | DateValue | The latest selectable date. | |
granularity | 'day' | 'hour' | 'minute' | 'second' | 'day' | The smallest unit the field edits. |
locale | string | 'en-US' | BCP 47 locale for segment order, month names, and the names of the calendar's month buttons. |
name | string | Name for form submission. | |
disabled | boolean | Disable the picker. Defaults to the enclosing field's disabled. | |
required | boolean | Make a date required. Defaults to the enclosing field's required. | |
readonly | boolean | false | Make the field read-only. |
children | Snippet | The 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.
| Prop | Type | Default | Description |
|---|---|---|---|
id | string | Element 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. |
sideOffset | number | 4 | Gap in pixels between the trigger and the panel. |
alignOffset | number | 0 | Shift in pixels along the alignment axis. |
portal | PortalTarget | true | Where 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>| Prop | Type | Default | Description |
|---|---|---|---|
id | string | Element id. null is not accepted. | |
state | FieldState | Contextual 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>| Prop | Type | Default | Description |
|---|---|---|---|
id | string | Element id. null is not accepted. | |
disabled | boolean | Disable 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.