DateRangePicker
A date range picker: one segmented field holding a start and an end date, with a range calendar
that opens from a trigger. Render DateRangePicker.Field with a
DateRangePicker.Trigger inside it, and
DateRangePicker.Content holding a
DateRangePicker.Calendar. Inside a Field
it takes disabled and required from there.
The value is a DateRange, a start and an end that are each a DateValue from
@internationalized/date. It is undefined until a date is chosen. With one end chosen, the
other is undefined, so a finished range is one with both set. Picking the end before the start
in the calendar swaps them, so start is never after end.
Built on bits-ui DateRangePicker.
<DateRangePicker bind:value> <DateRangePicker.Field> <DateRangePicker.Trigger /> </DateRangePicker.Field> <DateRangePicker.Content> <DateRangePicker.Calendar /> </DateRangePicker.Content></DateRangePicker>start: none, end: none
- Composed from parts, so the field, its trigger, and the calendar are yours to arrange.
- One
value, bindable, with astartand anend.openis bindable too.minandmaxbound the selectable dates. granularitysets the smallest unit the field edits, fromdaydown tosecond.DateRangePicker.Fieldtakesstatefrom an enclosingField, or directly.errorandwarnshare theinputcomponent class withInput.- The calendar floats in a portal, positioned to the field, and shades the days between the two ends.
- 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 DateRangePicker. Field is the segmented input, holding the start date, a dash, the end date, and the Trigger button that opens the calendar. Content is the floating panel, portaled to the body, and holds the Calendar.
<DateRangePicker> <DateRangePicker.Field> <DateRangePicker.Trigger /> </DateRangePicker.Field> <DateRangePicker.Content> <DateRangePicker.Calendar /> </DateRangePicker.Content></DateRangePicker>Two-way binding
Section titled “Two-way binding”bind:value on the root. The value is a DateRange, an object with a start and an end that are each a DateValue from @internationalized/date. It is undefined until a date is chosen. With only one end chosen, the other is undefined, so a finished range is one with both ends set. Picking the end before the start in the calendar swaps them, so start is never after end.
name submits the range as an ISO 8601 interval, <start>/<end>, and submits an empty value until both ends are set.
- start:
none - end:
none - status: nothing chosen
Code
<script lang="ts"> import type { ComponentProps } from "svelte";
import { DateRangePicker, Field, Label } from "@viamrobotics/prime-ui";
let value = $state<ComponentProps<typeof DateRangePicker>["value"]>();
const status = $derived.by(() => { if (!value) return "nothing chosen"; if (value.start && value.end) return "finished range"; return "half chosen, pick an end"; });</script>
<div class="not-content"> <Field class="flex max-w-sm flex-col gap-1"> <Label>Reporting period</Label> <DateRangePicker bind:value name="period"> <DateRangePicker.Field> <DateRangePicker.Trigger /> </DateRangePicker.Field> <DateRangePicker.Content> <DateRangePicker.Calendar /> </DateRangePicker.Content> </DateRangePicker> </Field>
<ul class="mt-3 flex flex-col gap-1 text-sm text-subtle-2"> <li>start: <code>{value?.start?.toString() ?? "none"}</code></li> <li>end: <code>{value?.end?.toString() ?? "none"}</code></li> <li>status: {status}</li> </ul></div>Fully controlled
Section titled “Fully controlled”Pass bind:value a getter and a setter. The setter can refuse a range by leaving the value as it was. State & binding explains both modes.
Ranges longer than 7 days are declined by the setter, so picking one changes nothing.
start: none, end: none
Code
<script lang="ts"> import type { ComponentProps } from "svelte";
import { DateRangePicker, Field, Hint, Label } from "@viamrobotics/prime-ui";
const MAX_DAYS = 7;
let value = $state<ComponentProps<typeof DateRangePicker>["value"]>();
const withinLimit = (next: typeof value) => { if (!next?.start || !next.end) return true; return next.start.add({ days: MAX_DAYS - 1 }).compare(next.end) >= 0; };</script>
<div class="not-content"> <Field class="flex max-w-sm flex-col gap-1"> <Label>Export window</Label> <DateRangePicker bind:value={ () => value, (next) => { if (withinLimit(next)) value = next; } } > <DateRangePicker.Field> <DateRangePicker.Trigger /> </DateRangePicker.Field> <DateRangePicker.Content> <DateRangePicker.Calendar /> </DateRangePicker.Content> </DateRangePicker> <Hint> Ranges longer than {MAX_DAYS} days are declined by the setter, so picking one changes nothing. </Hint> </Field>
<p class="mt-3 text-sm text-subtle-2"> start: <code>{value?.start?.toString() ?? "none"}</code>, end: <code>{value?.end?.toString() ?? "none"}</code> </p></div>In a field
Section titled “In a field”An enclosing Field supplies the label, hint, disabled, required, and state. The visible Label names the segmented field.
The first and last day of the invoice.
Code
<script lang="ts"> import { DateRangePicker, Field, Hint, Label } from "@viamrobotics/prime-ui";</script>
<div class="not-content"> <Field class="flex max-w-sm flex-col gap-1" required> <Label>Billing period</Label> <DateRangePicker> <DateRangePicker.Field> <DateRangePicker.Trigger /> </DateRangePicker.Field> <DateRangePicker.Content> <DateRangePicker.Calendar /> </DateRangePicker.Content> </DateRangePicker> <Hint>The first and last day of the invoice.</Hint> </Field></div>Bounds
Section titled “Bounds”min and max take date objects from @internationalized/date, such as new CalendarDate(2026, 1, 1). Dates outside the bounds cannot be selected in the calendar. A date typed outside them marks the field aria-invalid and paints the same error border as state="error".
Time of day
Section titled “Time of day”granularity of hour, minute, or second adds a time of day to each end, as on DatePicker.
Presets
Section titled “Presets”A preset such as “last 24 hours” belongs beside the control in the consuming app. It sets value to a range, and the picker shows it like any other.
Accessible names
Section titled “Accessible names”DateRangePicker.Trigger takes aria-label, which defaults to “Open calendar”. DateRangePicker.Content takes aria-label, which defaults to “Choose a date range”. DateRangePicker.Calendar takes aria-label too. It replaces “Choose a date range” 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.
Placement
Section titled “Placement”DateRangePicker.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 and last day of the invoice.
Error
Pick both a start and an end date.
Warn
This period is in the past.
Disabled
Read only
Minute granularity
Styling
Section titled “Styling”DateRangePicker.Field, DateRangePicker.Trigger, and DateRangePicker.Calendar take class on the element they render. DateRangePicker takes no class, since it renders no element of its own. DateRangePicker.Trigger takes button attributes, and its children replace the calendar icon. DateRangePicker.Content wears z-popover. See z layers.
Each day in the calendar carries these data attributes, set by bits-ui:
| Attribute | Set when |
|---|---|
data-selection-start |
The day is the start of the range. |
data-selection-end |
The day is the end of the range. |
data-range-start |
The day is the start of the range. |
data-range-end |
The day is the end of the range, or the start while no end is set. |
data-range-middle |
The day is selected and is neither end. |
data-selected |
The day is in the chosen range, ends included. |
data-highlighted |
The day is in the preview between the start and the hovered or focused day. |
data-focused |
The day holds the calendar’s focus position. |
data-today |
The day is today. |
data-outside-month |
The day belongs to a neighboring month. |
data-outside-visible-months |
The day is outside every month on show. |
data-disabled |
The day is disabled or outside min and max. |
data-unavailable |
The day is unavailable. |
The field frame sets data-state to open or closed, data-disabled, data-readonly, and data-field-state for error and warn. Each segment sets data-segment to its part, along with data-invalid, data-disabled, and data-readonly.
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. |
| Backspace | Clears the 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 | Picks the focused day, as the start first and then as the end. |
| Escape | Closes the calendar. |
| Prop | Type | Default | Description |
|---|---|---|---|
bind:value | DateRange | The selected range. Two-way bindable. undefined until a date is chosen, and the
unchosen end is undefined while only one is set. | |
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. The submitted value is the ISO 8601 interval
<start>/<end>, or empty unless both ends are set. | |
disabled | boolean | Disable the picker. Defaults to the enclosing field's disabled. | |
required | boolean | Make a range required. Defaults to the enclosing field's required. | |
readonly | boolean | false | Make the field read-only. |
children | Snippet | The DateRangePicker.* parts. |
DateRangePicker.Calendar
The month calendar of a DateRangePicker: a header with the previous
and next month buttons around the month heading, the weekday names, and the day grid. Render it
inside DateRangePicker.Content.
The first day picked is the start and the second is the end. Picking an earlier day second swaps
them. While only the start is set, the days between it and the hovered or focused day are shaded
as a preview. Arrow keys move between days, and Enter or Space picks 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.
<DateRangePicker.Content> <DateRangePicker.Calendar aria-label="Choose a reporting period" /></DateRangePicker.Content>Takes extraClasses, 'aria-label': label, ...restProps }: Props as its props.
DateRangePicker.Content
The floating panel of a DateRangePicker, portaled to the body.
Render a DateRangePicker.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.
DateRangePicker.Field
The segmented field of a DateRangePicker: the start date’s segments,
a dash, and the end date’s segments in one frame. Each part of a date is its own editable segment:
type digits, or press the arrow keys to step it. Completing the start date moves focus on to the
end date. Place a DateRangePicker.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.
<DateRangePicker.Field> <DateRangePicker.Trigger /></DateRangePicker.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.
DateRangePicker.Trigger
The button that opens the calendar of a DateRangePicker. Place it
inside DateRangePicker.Field, after the segments. It shows a
calendar icon, and children replace the icon.
<DateRangePicker.Field> <DateRangePicker.Trigger aria-label="Pick a reporting period" /></DateRangePicker.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 range picker is disabled
or readonly, so a read-only picker cannot open its calendar. |
Plus everything in HTMLButtonAttributes, spread onto the element.