DateRangePicker
A calendar popover for picking a start and end date, for travel dates, a booking window, or a reporting period. It builds on DatePicker: same sizes, variants, constraints, and locale handling.
Playground
<DateRangePicker
label="Travel dates"
/>01 Examples
Booking a stay
closeOnSelect (the default) dismisses the popover once the range is complete, so the flow ends without a second gesture.<script lang="ts">
import { DateRangePicker, type DateRange } from '@urbicon-ui/blocks';
let stay = $state<DateRange | undefined>(undefined);
</script>
<DateRangePicker
label="Check-in / check-out"
bind:value={stay}
placeholder="Pick your dates"
clearable
/>Bounded to a bookable window
minDate and maxDate fence the calendar; isDateDisabled blocks the irregular gaps a fixed range cannot express, here every Sunday.<script lang="ts">
import { DateRangePicker, type DateRange } from '@urbicon-ui/blocks';
let bookable = $state<DateRange | undefined>(undefined);
const TODAY = new Date(2026, 7, 3);
const IN_90_DAYS = new Date(2026, 10, 1);
</script>
<DateRangePicker
label="Bookable period"
bind:value={bookable}
minDate={TODAY}
maxDate={IN_90_DAYS}
isDateDisabled={(d) => d.getDay() === 0}
helper="Next 90 days, Sundays excluded"
/>Reporting period in a form
name writes two hidden inputs, period_start and period_end, each carrying the serialised date, so the submitted form has the ISO values, not the locale-formatted display text. An empty range submits both as an empty string.<script lang="ts">
import { DateRangePicker, type DateRange } from '@urbicon-ui/blocks';
let reportRange = $state<DateRange | undefined>(undefined);
</script>
<DateRangePicker
label="Reporting period"
name="period"
bind:value={reportRange}
required
helper="Submitted as period_start and period_end"
/>02 Customization
The trigger and the calendar are styled separately: inputVariant takes the Input ladder (outlined, filled, ghost, underline) and calendarVariant the Calendar one (default, bordered, ghost). size applies to both.
The calendar props pass straight through: locale, weekStartsOn, showWeekNumbers, showOutsideDays, fixedWeeks. locale defaults to 'auto', which follows the active <I18nProvider>, so an app that already declares
its language does not repeat it here.
For a single date use DatePicker; for the calendar without an input, see Calendar. See Customization for the general contract.
03 Accessibility
Popup state on the calendar button
The text field carries aria-haspopup="dialog", so
assistive tech reports that a calendar exists. The calendar button beside it carries aria-expanded and, while the calendar is open, aria-controls pointing at the calendar.
Keyboard
↓ opens the calendar from the field; on the calendar button, Enter or Space opens and closes it. Opening leaves focus where it is, and Tab from the calendar button moves into the calendar, whose grid navigation follows the Calendar pattern. From inside the calendar, Esc or completing a range returns focus to the calendar button. In the field, Enter closes an open calendar and otherwise commits what you typed. Esc closes the calendar; with the calendar already closed, it discards a typed draft and keeps the selection.
Both embedded buttons are named
When clearable is set the field carries two controls,
and each gets its own localized aria-label: "Clear input" and "Open calendar".
Typing is a first-class path
The range can be typed as well as clicked. What you type is parsed on Enter with the calendar closed, when the calendar button opens the calendar, and
when focus leaves the picker; moving to its own buttons or into the calendar keeps the draft.
A parse failure shows as the field's error.
Dismissal is separable from notification
closeOnEscape and closeOnClickOutside govern whether the popover
closes; onEscape and onClickOutside only tell you it happened.
04 API Reference
37 propsProp | Type | Default | Description | |
|---|---|---|---|---|
calendarVariant | defaultborderedghost | 'default' | Visual style of the calendar popup. | |
class | string | — | Extra classes merged onto the positioning wrapper, the base slot. | |
clearable | boolean | true | Allow clearing the selected range: a clear button appears in the field while it holds a range. | |
closeOnClickOutside | boolean | true | Whether the popover closes on outside click. | |
closeOnEscape | boolean | true | Whether the popover closes on Escape key. | |
closeOnSelect | boolean | true | Close popover after selecting both dates. | |
defaultMonth | MonthIndex 0123 +8 more | — | Default month shown when the picker opens without a value. 0–11. | |
defaultYear | number | — | Default year shown when the picker opens without a value. | |
disabled | boolean | false | Disable the entire picker. | |
displayFormat | DateFormatOptions | — | Intl.DateTimeFormat options for displayed dates. | |
error | string | — | Error message shown below the input. While set, it takes the place of the picker's own message for a range it cannot parse or that falls outside the allowed dates. | |
fixedWeeks | boolean | true | Always show 6 week rows, so the overlay keeps its height while paging
months. Set false to let it shrink to 4 or 5 rows. | |
helper | string | — | Helper text shown below the input. | |
inputVariant | outlinedfilledghostunderline | 'outlined' | Input variant. | |
isDateDisabled | (date: Date) => boolean | — | Disables every day it returns true for, on top of minDate/maxDate — the one way
to disable single days, whether a rule (weekends) or a list (holidays). Only a range's
two ends are checked: the calendar cannot start or end a range on a disabled day, and a
typed range with a disabled end is rejected as out of range, but a range may span
disabled days. It receives a Date of its own for each day — read only its calendar
day. It runs again when $state it reads changes. Compare calendar days, not Date
objects (list.includes(d) matches nothing): keep a list as a Set of toIso keys
from @urbicon-ui/blocks/date and pass (d) => blocked.has(toIso(d)). It must not
throw; the calendar does not catch it. | |
label | string | — | Label above the input. | |
locale | string | 'auto' | BCP 47 locale tag for date formatting — month names, weekday names and the
header title. Defaults to 'auto', which follows the active
<I18nProvider> locale, so an app that already declares its language does
not have to repeat it here. SSR-safe: the locale comes from context, so the
server and the client resolve the same tag (Intl with undefined would
follow the runtime and disagree across hydration). Falls back to the base
locale (en) when no provider is mounted. Pass an explicit tag
(e.g. 'de-DE', 'ja-JP') to override. | |
maxDate | Date | — | Latest selectable date. | |
minDate | Date | — | Earliest selectable date. | |
mint | MintProp | 'none' | Micro-interaction preset forwarded to the inner Input. | |
name | string | — | Shared base name for native form submission. When set, two hidden
inputs are rendered — {name}_start and {name}_end — each
carrying the serialized date, so the visible input's locale-formatted
display string is never submitted instead.
Empty range submits both halves as "". The _start / _end
convention reflects the picker's domain language — date ranges read
naturally as start/end rather than min/max. | |
onClickOutside | () => void | — | Notification only — does NOT govern close behavior. | |
onEscape | () => void | — | Notification only — does NOT govern close behavior. | |
onOpenChange | (open: boolean) => void | — | Fires when the popover opens or closes. | |
onValueChange | (value: DateRange | undefined) => void | — | Fires when the selected range changes. In the calendar the user clicks
twice, once for the start and once for the end, and it fires on the
second click, once the range is complete (start ≠ end). The intermediate
{ start: d, end: d } state after the first click is not reported; use
bind:value if you need it. | |
placeholder | string | — | Placeholder when no range is selected. | |
preset | string | — | Apply a named preset registered on <BlocksProvider>. | |
required | boolean | false | Mark input as required: the label gets an asterisk and the text field the
native required attribute. | |
showOutsideDays | boolean | true | Show days from adjacent months. | |
showWeekNumbers | boolean | false | Show ISO week numbers. | |
size | xssmmdlg +1 more | 'md' | Component size. | |
slotClasses | Partial<Record<DatePickerSlots, string>> | — | Per-slot class overrides. base is the positioning wrapper the field and
the popover anchor sit in, iconButton the clear / open-calendar buttons
in the field's right-icon area. The field itself is an Input and the
overlay a Calendar; restyle those under their own names. | |
unstyled | boolean | — | Strip the default tv() classes of the wrapper AND of the Input, Popover and Calendar it renders; slotClasses and class then stand alone. | |
value | DateRange | — | Currently selected date range. Supports bind:value. | |
valueFormat | dateiso | 'date' | Format used to serialise both range halves for the hidden form inputs.
- 'date' (default): YYYY-MM-DD in the local timezone — matches
the native <input type="date"> payload and Zod schemas like
z.string().regex(/^\d{4}-\d{2}-\d{2}$/).transform((v) => new Date(v)).
- 'iso': full ISO-8601 with Z suffix (UTC). Use this when the
downstream schema expects a parseable timestamp string (e.g. a
Drizzle timestamp({ withTimezone: true, mode: 'date' }) column).
Only relevant when DateRangePickerProps.name is set. | |
weekStartsOn | WeekdayIndex 0123 +3 more | 1 | First day of the week. 0 = Sunday, 1 = Monday. | |
...HTMLAttributes<HTMLDivElement> inherited | HTMLAttributes | — | HTML attributes (excluding: 'children') |
05 Types
Name | Kind | Category | Used by | Description | |
|---|---|---|---|---|---|
DatePickerProps | interface | props | — | — | |
DateRangePickerProps | interface | props | — | — | |
DatePickerPreset | interface | helper | — | — | |
DateRangePreset | interface | helper | — | — | |
MintProp | type | helper | 1 | — | |
MonthIndex | type | helper | 1 | Month index used by Date#getMonth(). | |
WeekdayIndex | type | helper | 1 | Weekday index used by Date#getDay(). | |
DateRange | interface | helper | 1 | An inclusive start/end date pair: a selected range, a visible window, the
range onNavigate reports. One type for Calendar, Planner and
ResourceTimeline alike.
ResourceTimeline.getRange is not this type: it also accepts local date
strings ('2026-06-16'), which a selection value must not. | |
DateFormatOptions | type | helper | 1 | — | |
MintName | type | helper | — | A mint name: a built-in (autocompleted), 'none' to disable, or any
consumer-registered name. (string & {}) keeps the registry open — a
custom name still type-checks, it just isn't suggested. A typo therefore
also still compiles (it resolves like an unregistered custom name and
warns at runtime); the union buys completion and docs, not validation. | |
MintConfig | interface | helper | — | — | |
BuiltinMintName | type | helper | — | Built-in mint names as a literal union, so the mint prop autocompletes
across every component — the single list the hand-curated playground knobs
and docs used to drift away from. |
06 Installation
Import
import { DateRangePicker } from '@urbicon-ui/blocks';