Skip to content

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>
mmddyyyy mmddyyyy

start: none, end: none

  • Composed from parts, so the field, its trigger, and the calendar are yours to arrange.
  • One value, bindable, with a start and an end. open is bindable too. min and max bound the selectable dates.
  • granularity sets the smallest unit the field edits, from day down to second.
  • DateRangePicker.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, and shades the days between the two ends.
  • While the calendar is open, the field shows the darker border-gray-9 frame, as Select.Trigger does.

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>

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.

mmddyyyy mmddyyyy
  • start: none
  • end: none
  • status: nothing chosen
Code
TwoWay.svelte
<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>

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.

mmddyyyy mmddyyyy

Ranges longer than 7 days are declined by the setter, so picking one changes nothing.

start: none, end: none

Code
Controlled.svelte
<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>

An enclosing Field supplies the label, hint, disabled, required, and state. The visible Label names the segmented field.

mmddyyyy mmddyyyy

The first and last day of the invoice.

Code
InField.svelte
<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>

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".

granularity of hour, minute, or second adds a time of day to each end, as on DatePicker.

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.

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.

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.

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 mmddyyyy

In a field, with label and hint

mmddyyyy mmddyyyy

The first and last day of the invoice.

Error

mmddyyyy mmddyyyy

Pick both a start and an end date.

Warn

mmddyyyy mmddyyyy

This period is in the past.

Disabled

mmddyyyy mmddyyyy

Read only

mmddyyyy mmddyyyy

Minute granularity

mmddyyyy––––AM mmddyyyy––––AM

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.

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.
BackspaceClears the 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 / SpacePicks the focused day, as the start first and then as the end.
EscapeCloses the calendar.
PropTypeDefaultDescription
bind:valueDateRangeThe selected range. Two-way bindable. undefined until a date is chosen, and the unchosen end is undefined while only one is set.
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. The submitted value is the ISO 8601 interval <start>/<end>, or empty unless both ends are set.
disabledbooleanDisable the picker. Defaults to the enclosing field's disabled.
requiredbooleanMake a range required. Defaults to the enclosing field's required.
readonlybooleanfalseMake the field read-only.
childrenSnippetThe 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.

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.

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>
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.

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>
PropTypeDefaultDescription
idstringElement id. null is not accepted.
disabledbooleanDisable 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.