Date Range Picker

Editable start and end dates with a shared calendar popup.

Travel dates

09172026

09232026

Installation

pnpm dlx @mielui/svelte add date-range-picker

Usage

Compose two Inputs with type="start" and type="end". Each Input accepts its own form name. Bind an object with start and end DateValue properties; either endpoint can be undefined while editing.

<script lang="ts">
    import type { DateValue } from '@internationalized/date';
    import * as DateRangePicker from '@mielui/svelte/components/date-range-picker';

    let value = $state<{
        start: DateValue | undefined;
        end: DateValue | undefined;
    }>({
        start: undefined,
        end: undefined
    });
</script>

<DateRangePicker.Root bind:value>
    <DateRangePicker.Label>Travel dates</DateRangePicker.Label>
    <DateRangePicker.Input type="start" name="arrival" aria-label="Arrival" />
    <DateRangePicker.Input type="end" name="departure" aria-label="Departure" />
    <DateRangePicker.Trigger />
    <DateRangePicker.Content align="end">
        <DateRangePicker.Calendar />
    </DateRangePicker.Content>
</DateRangePicker.Root>

Use CalendarDate from @internationalized/date for date-only values, or parseDate for ISO date strings. Bind placeholder to control the visible month. An explicit locale and placeholder keep server and client formatting predictable. Avoid converting a date-only selection through a UTC JavaScript Date to store it. Save each end with value.start?.toString() and value.end?.toString().

Examples

Helper text

A line under the fields tells people they can type each date or pick the range.

Travel dates

09172026

09232026

Choose a start and end date, or edit each field.

Two months

numberOfMonths shows several months side by side, and pagedNavigation moves the arrows by that many. A range can start in one month and end in the next. Months wrap in narrow containers.

Booking dates

mmddyyyy

Range length

minDays and maxDays limit how long a range can be, counting both endpoints. Picking an end date outside the limit starts a new range from that date, so tell people the limit next to the field.

Stay

mmddyyyy

Stays run from 3 to 14 days.

Disabled

disabled turns off both fields and the trigger. readonly keeps the calendar navigable but blocks changes to the value.

Dates are locked

mmddyyyy

Forms and reset

A named Input submits its ISO date value. Required and invalid fields block submission; focus moves to the visible date segments. Disabled fields are omitted. Reset restores the initial selection. Input also accepts form to associate it with an external form.

Composition and accessibility

Calendar exposes a children snippet with months and weekdays. Keep the default Month, or compose Grid, GridHead, GridBody, GridRow, HeadCell, Cell and Day to restyle individual regions. Month also accepts a day(date) snippet. Header, Heading, PrevButton, NextButton, MonthSelect and YearSelect can be omitted, reordered or replaced with another documented composition.

Styled parts forward native attributes and expose bind:element for their underlying element. Arrow keys move between days, Page Up and Page Down change the visible month, and Enter or Space selects. Focus and selection are distinct. Disabled dates cannot be selected; readonly calendars remain navigable. The today indicator and unavailable strike-through provide cues beyond color.

Input exposes a children snippet with segments for custom field composition. Render each Segment with its part to preserve keyboard editing. Put name on Input for ISO-value form submission, and required or validation callbacks on Root. Use errorMessageId to connect your error message. Popup focus returns to the trigger when dismissed; motion respects reduced-motion preferences.

Labels

Built-in text is English. Pass a DateRangePickerLabels object to labels on Root to translate or reword the trigger name, the panel name and the validation message. Every key is optional, and an omitted key keeps its English default.

<script lang="ts">
    import * as DateRangePicker from '@mielui/svelte/components/date-range-picker';
    import type { DateRangePickerLabels } from '@mielui/svelte/components/date-range-picker';

    const labels: DateRangePickerLabels = {
        trigger: 'Choisir des dates',
        content: 'Calendrier',
        invalid: 'Saisissez une date valide.'
    };
</script>

<DateRangePicker.Root locale="fr-FR" {labels}>
    <DateRangePicker.Label>Dates du séjour</DateRangePicker.Label>
    <DateRangePicker.Input type="start" name="arrival" aria-label="Arrivée" />
    <DateRangePicker.Input type="end" name="departure" aria-label="Départ" />
    <DateRangePicker.Trigger />
    <DateRangePicker.Content align="end">
        <DateRangePicker.Calendar />
    </DateRangePicker.Content>
</DateRangePicker.Root>

Range events

onValueChange runs when the range changes. onStartValueChange and onEndValueChange report each end as it is picked, before the range is complete. preventDeselect stops a click on a selected end from clearing the range, and onPlaceholderChange runs when the visible month changes.

The panel closes once both ends are picked. Set closeOnRangeSelect={false} to keep it open. Bind open to control it yourself, with onOpenChange for each change and onOpenChangeComplete for the moment the animation ends.

Report period

mmddyyyy

From not picked. To not picked.

Unavailable and disabled dates

isDateDisabled removes a date from play: it cannot be focused or picked. isDateUnavailable is softer. An unavailable date is struck through and can still be focused, so keyboard users can read why it is off limits, and picking it marks the value invalid.

A range can be drawn across disabled dates. Set excludeDisabled to clear the range whenever it would contain one. validate receives the range and returns an error message when your own rule rejects it, and onInvalid runs with the reason and that message.

Time off

mmddyyyy

Grid, formats and the typed fields

weekStartsOn sets the first column, from 0 for Sunday to 6 for Saturday, and falls back to the locale. weekdayFormat picks narrow, short or long weekday names. fixedWeeks is on by default and always draws six rows so the height never jumps between months. Turn it off to draw only the weeks a month needs. Days from the neighbouring months fill the grid and cannot be selected. Set disableDaysOutsideMonth={false} to make them selectable.

monthFormat and yearFormat on Root control how the heading and the selects name months and years. Each takes an Intl style such as short or 2-digit, or a function that receives the number and returns the text. MonthSelect and YearSelect take the same two props to override the format for their own options, and YearSelect takes years, the exact list of years to offer.

The typed field has its own options on Root. granularity decides which segments it shows, from day down to second, hourCycle picks a 12 or 24 hour clock, and hideTimeZone drops the zone name. readonlySegments locks the segments you list while the rest stay editable.

Panel position and dismissal

Content positions the calendar panel. side picks the edge of the field it opens from and flips when there is no room, sideOffset is the gap in pixels, and alignOffset nudges it along that edge. avoidCollisions, collisionBoundary and collisionPadding control how it stays inside the viewport or another container. sticky keeps it in view while the field scrolls, hideWhenDetached hides it once the field scrolls away, and customAnchor positions it against a different element. strategy switches between absolute and fixed positioning, updatePositionStrategy set to always re-measures every frame for a field that moves, and arrowPadding and dir cover arrows and right-to-left text.

The same part owns dismissal and focus. interactOutsideBehavior and escapeKeydownBehavior take close, ignore, or one of the two defer values that ask a parent layer first. onInteractOutside, onFocusOutside and onEscapeKeydown run for each event and can call preventDefault() to keep the panel open. trapFocus, preventScroll and preventOverflowTextSelection decide whether Tab, page scrolling and text selection can leave the panel, and onOpenAutoFocus and onCloseAutoFocus let you redirect focus when it opens and closes. surface picks solid or glass, and portal={false} renders the panel in place.

When you compose the calendar yourself, every part except Root and Month accepts child, a snippet that receives the part's props so you can render your own element with them, and style for inline styles. Month takes showHeading to print the month name above its grid, which Root turns on by itself when it shows more than one month.

Root, Input, Trigger, Calendar and Content also accept style. Trigger takes openOnHover with openDelay and closeDelay to open the panel when the pointer rests on it.

API reference

DateRangePicker.Root

children

Snippet<[]>
Content rendered inside.
id

string
Id of the element.
placeholder Bindable

DateValue
The placeholder value of the date field. This determines the format and what date the field starts at when it is empty.
style

string | StyleProperties | null
Inline styles for the element.
disabled

boolean
If true, the date field will be disabled and users will not be able to interact with it. This also disables the hidden input element if the date field is used in a form.

Default false
value Bindable

DateRange
The value of the date picker.
readonly

boolean
If true, the date field will be readonly, and users will not be able to edit the values of any of the individual segments.

Default false
required

boolean
Whether or not the hidden input of the date field requires a value to be submitted.

Default false
onValueChange

OnChangeFn<DateRange>
A callback function called when the value changes.
onPlaceholderChange

OnChangeFn<DateValue>
A callback function called when the placeholder value changes.
preventDeselect

boolean
Whether or not users can deselect a date once selected without selecting another date.
minValue

DateValue
The minimum acceptable date. When provided, the date field will be marked as invalid if the user enters a date before this date.
maxValue

DateValue
The maximum acceptable date. When provided, the date field will be marked as invalid if the user enters a date after this date.
pagedNavigation

boolean
Applicable only when numberOfMonths is greater than 1.
weekStartsOn

WeekStartsOn
The day of the week to start the calendar on, which must be a number between 0 and 6, where 0 is Sunday and 6 is Saturday.
weekdayFormat

"long" | "narrow" | "short"
How the string representation of the weekdays provided via the weekdays state store should be formatted.

Default 'short'
isDateDisabled

DateMatcher
A function that returns true if the given date is disabled, which makes the date unable to be selected in the calendar.
isDateUnavailable

DateMatcher
A function that returns true if the given date is unavailable, where if selected, the date field will be marked as invalid.
fixedWeeks

boolean
Display 6 weeks per month, regardless the month's number of weeks. This is useful for displaying a consistent calendar, where the size of the calendar doesn't change month to month.

Default true
numberOfMonths

number
Determines the number of months to display on the calendar simultaneously. For navigation between months, refer to the pagedNavigation prop.
calendarLabel

string
This label is exclusively used for accessibility, remaining hidden from the page. It's read by screen readers when the calendar is opened. The current month and year are automatically appended to the label, so you only need to provide the base label.
locale

string
The locale to use for formatting the date field.

Default 'en-US'
disableDaysOutsideMonth

boolean
Whether to disable the selection of days outside the current month. By default, days outside the current month are rendered to fill the calendar grid, but they are not selectable. Setting this prop to true will disable this behavior.

Default true
maxDays

number
The maximum number of days that can be selected in a range.
monthFormat

"numeric" | "long" | "short" | "narrow" | "2-digit" | ((month: number) => string)
The format of the month names in the calendar.
yearFormat

"numeric" | "2-digit" | ((year: number) => string)
The format of the year names in the calendar.
open Bindable

boolean
The open state of the date picker popover.

Default false
onOpenChange

OnChangeFn<boolean>
A callback function called when the open state changes.
onOpenChangeComplete

OnChangeFn<boolean>
A callback function called when the open state changes complete.
validate

DateRangeValidator
A function that returns a string or array of strings as validation errors if the date is invalid, or nothing if the date is valid
onInvalid

DateOnInvalid
A callback fired when the date field's value is invalid. Use this to display an error message to the user.
readonlySegments

("month" | "year" | "day" | "hour" | "minute" | "second" | "dayPeriod")[]
An array of segment names that should be readonly. If provided, only the segments not in this array will be editable.
hourCycle

12 | 24
The format to use for displaying the time in the input. If using a 12 hour clock, ensure you also include the dayPeriod segment in your input to ensure the user can select AM/PM.
granularity

Granularity
The granularity of the date field. This determines which segments will be includes in the segments array used to build the date field.
hideTimeZone

boolean
Whether or not to hide the timeZoneName segment from the date field.
errorMessageId

string
The id of the element which contains the error messages for the date field when the date is invalid.
closeOnRangeSelect

boolean
Whether to close the popover when a date range is selected.
onStartValueChange

OnChangeFn<DateValue | undefined>
A callback function called when the start value changes. This doesn't necessarily mean the value has updated and should be used to apply cosmetic changes to the calendar when only part of the value is changed/completed.
onEndValueChange

OnChangeFn<DateValue | undefined>
A callback function called when the end value changes. This doesn't necessarily mean the value has updated and should be used to apply cosmetic changes to the calendar when only part of the value is changed/completed.
minDays

number
The minimum number of days that can be selected in a range.
excludeDisabled

boolean
Whether to automatically reset the range if any date within the selected range becomes disabled. When true, the entire range will be cleared if a disabled date is found between the start and end dates.
element Bindable

HTMLElement | null
Bindable reference to the DOM element.

Default null
labels

DatePickerLabels
Overrides the built-in text and accessible names. Every key is optional and English is the fallback.

DateRangePicker.Content

children

Snippet<[]>
Content rendered inside.
dir

Direction
The text direction of the content.
id

string
Id of the element.
style

string | StyleProperties | null
Inline styles for the element.
align

"center" | "end" | "start"
The preferred alignment of the anchor to render against when open. This may change when collisions occur.

Default 'start'
onInteractOutside

InteractOutsideEventHandler
Callback fired when an outside interaction event completes, which is either a pointerup, mouseup, or touchend event, depending on the user's input device.
interactOutsideBehavior

InteractOutsideBehaviorType
Interact outside behavior type. close: Closes the element immediately. defer-otherwise-close: Delegates the action to the parent element. If no parent is found, it closes the element. defer-otherwise-ignore: Delegates the action to the parent element. If no parent is found, nothing is done. ignore: Prevents the element from closing and also blocks the parent element from closing in response to an outside interaction.
onFocusOutside

((event: FocusEvent) => void)
Callback fired when focus leaves the dismissible layer.
preventScroll

boolean
Whether to prevent scrolling the body when the content is open. Whether to prevent body scrolling when the content is open.
onEscapeKeydown

((e: KeyboardEvent) => void)
Callback fired when escape is pressed.
escapeKeydownBehavior

EscapeBehaviorType
Escape behavior type. close: Closes the element immediately. defer-otherwise-close: Delegates the action to its parent component that has an escape keydown handler. If no parent is found, it closes the element. defer-otherwise-ignore: Delegates the action to the parent element. If no parent is found, nothing is done. ignore: Prevents the element from closing and also blocks the parent element from closing in response to an escape key press.
side

"bottom" | "left" | "right" | "top"
The preferred side of the anchor to render against when open. Will be reversed when collisions occur.
sideOffset

number
The distance in pixels from the anchor to the floating element.

Default 6
alignOffset

number
An offset in pixels from the "start" or "end" alignment options.
arrowPadding

number
This describes the padding between the arrow and the edges of the floating element. If your floating element has border-radius, this will prevent it from overflowing the corners.
avoidCollisions

boolean
When true, overrides the side and align options to prevent collisions with the boundary edges.
collisionBoundary

Arrayable<Boundary>
A boundary element or array of elements to check for collisions against.
collisionPadding

number | Partial<Record<"left" | "right" | "top" | "bottom", number>>
The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.

Default 8
sticky

"partial" | "always"
Keeps the panel in view while its anchor scrolls. partial keeps part of it visible and always keeps all of it.
hideWhenDetached

boolean
Hides the panel when the trigger scrolls out of view.
updatePositionStrategy

"optimized" | "always"
"optimized" will only update the position when necessary, while "always" will update the position on each animation frame, which is useful if the floating content is following something like a mouse cursor.
strategy

"absolute" | "fixed"
The positioning strategy to use for the floating element.
customAnchor

string | HTMLElement | Measurable | null
Use an element other than the trigger to anchor the content to. If provided, the content will be anchored to the provided element instead of the trigger.
preventOverflowTextSelection

boolean
Passing true will prevent the overflow of text selection outside the element, provided the element is the top layer.
onOpenAutoFocus

EventCallback
Event handler called when auto-focusing on open. Can be prevented.
onCloseAutoFocus

EventCallback
Event handler called when auto-focusing on close. Can be prevented.
trapFocus

boolean
Whether focus is trapped within the focus scope.
element Bindable

HTMLElement | null
Bindable reference to the DOM element.

Default null
surface

"solid" | "glass"
Surface treatment. Omit it to inherit --mielui-surface from the theme.
portal

boolean
Moves the panel to the end of the document so ancestors cannot clip it. Set false to render it in place.

Default true

DateRangePicker.Segment

children

Snippet<[]>
Content rendered inside.
id

string
Id of the element.
part Required

"day" | "dayPeriod" | "hour" | "literal" | "minute" | "month" | "second" | "timeZoneName" | "year"
Which part of the date this segment edits.
style

string | StyleProperties | null
Inline styles for the element.
child

Snippet<[{ props: Record<string, unknown>; }]>
Renders your own element in place of the default one. Spread the given props onto it.
element Bindable

HTMLElement | null
Bindable reference to the DOM element.

Default null

DateRangePicker.Cell

children

Snippet<[CalendarCellSnippetProps]>
Content rendered inside.
id

string
Id of the element.
style

string | StyleProperties | null
Inline styles for the element.
date Required

CalendarDate | CalendarDateTime | ZonedDateTime
The date value of the cell.
month Required

CalendarDate | CalendarDateTime | ZonedDateTime
The month DateValue that this cell is being rendered in.
child

Snippet<[CalendarCellSnippetProps & { props: Record<string, unknown>; }]>
Renders your own element in place of the default one. Spread the given props onto it.
element Bindable

HTMLElement | null
Bindable reference to the DOM element.

Default null

DateRangePicker.Day

children

Snippet<[CalendarDaySnippetProps]>
Content rendered inside.
id

string
Id of the element.
style

string | StyleProperties | null
Inline styles for the element.
child

Snippet<[CalendarDaySnippetProps & { props: Record<string, unknown>; }]>
Renders your own element in place of the default one. Spread the given props onto it.
element Bindable

HTMLElement | null
Bindable reference to the DOM element.

Default null

DateRangePicker.Grid

children

Snippet<[]>
Content rendered inside.
id

string
Id of the element.
style

string | StyleProperties | null
Inline styles for the element.
child

Snippet<[{ props: Record<string, unknown>; }]>
Renders your own element in place of the default one. Spread the given props onto it.
element Bindable

HTMLElement | null
Bindable reference to the DOM element.

Default null

DateRangePicker.GridBody

children

Snippet<[]>
Content rendered inside.
id

string
Id of the element.
style

string | StyleProperties | null
Inline styles for the element.
child

Snippet<[{ props: Record<string, unknown>; }]>
Renders your own element in place of the default one. Spread the given props onto it.
element Bindable

HTMLElement | null
Bindable reference to the DOM element.

Default null

DateRangePicker.GridHead

children

Snippet<[]>
Content rendered inside.
id

string
Id of the element.
style

string | StyleProperties | null
Inline styles for the element.
child

Snippet<[{ props: Record<string, unknown>; }]>
Renders your own element in place of the default one. Spread the given props onto it.
element Bindable

HTMLElement | null
Bindable reference to the DOM element.

Default null

DateRangePicker.GridRow

children

Snippet<[]>
Content rendered inside.
id

string
Id of the element.
style

string | StyleProperties | null
Inline styles for the element.
child

Snippet<[{ props: Record<string, unknown>; }]>
Renders your own element in place of the default one. Spread the given props onto it.
element Bindable

HTMLElement | null
Bindable reference to the DOM element.

Default null

DateRangePicker.HeadCell

children

Snippet<[]>
Content rendered inside.
id

string
Id of the element.
style

string | StyleProperties | null
Inline styles for the element.
child

Snippet<[{ props: Record<string, unknown>; }]>
Renders your own element in place of the default one. Spread the given props onto it.
element Bindable

HTMLElement | null
Bindable reference to the DOM element.

Default null

DateRangePicker.Header

children

Snippet<[]>
Content rendered inside.
id

string
Id of the element.
style

string | StyleProperties | null
Inline styles for the element.
child

Snippet<[{ props: Record<string, unknown>; }]>
Renders your own element in place of the default one. Spread the given props onto it.
element Bindable

HTMLElement | null
Bindable reference to the DOM element.

Default null

DateRangePicker.Heading

children

Snippet<[CalendarHeadingSnippetProps]>
Content rendered inside.
id

string
Id of the element.
style

string | StyleProperties | null
Inline styles for the element.
child

Snippet<[CalendarHeadingSnippetProps & { props: Record<string, unknown>; }]>
Renders your own element in place of the default one. Spread the given props onto it.
element Bindable

HTMLElement | null
Bindable reference to the DOM element.

Default null

DateRangePicker.Month

class

string
Classes added to the element.
month Required

{ value: DateValue; weeks: DateValue[][]; dates: DateValue[]; }
Month data from the Root snippet.
weekdays Required

string[]
Weekday names from the Root snippet.
locale

string
BCP 47 locale used for names and number formats.

Default 'en-US'
showHeading

boolean
Shows the month name above the grid, for layouts with several months.

Default false
day

Snippet<[date: DateValue]>
Custom content for each day cell.

DateRangePicker.MonthSelect

children

Snippet<[CalendarMonthSelectSnippetProps]>
Content rendered inside.
id

string
Id of the element.
style

string | StyleProperties | null
Inline styles for the element.
child

Snippet<[CalendarMonthSelectSnippetProps & { props: Record<string, unknown>; }]>
Renders your own element in place of the default one. Spread the given props onto it.
monthFormat

"numeric" | "long" | "short" | "narrow" | "2-digit" | ((month: number) => string)
How the month names should be formatted in the select options.
months

number[]
An array of month numbers (1-12) to display in the select. This allows for flexible month selection, such as showing only specific months or seasons.
element Bindable

HTMLElement | null
Bindable reference to the DOM element.

Default null

DateRangePicker.NextButton

children

Snippet<[]>
Content rendered inside.
id

string
Id of the element.
style

string | StyleProperties | null
Inline styles for the element.
child

Snippet<[{ props: Record<string, unknown>; }]>
Renders your own element in place of the default one. Spread the given props onto it.
element Bindable

HTMLElement | null
Bindable reference to the DOM element.

Default null

DateRangePicker.PrevButton

children

Snippet<[]>
Content rendered inside.
id

string
Id of the element.
style

string | StyleProperties | null
Inline styles for the element.
child

Snippet<[{ props: Record<string, unknown>; }]>
Renders your own element in place of the default one. Spread the given props onto it.
element Bindable

HTMLElement | null
Bindable reference to the DOM element.

Default null

DateRangePicker.YearSelect

children

Snippet<[CalendarYearSelectSnippetProps]>
Content rendered inside.
id

string
Id of the element.
style

string | StyleProperties | null
Inline styles for the element.
child

Snippet<[CalendarYearSelectSnippetProps & { props: Record<string, unknown>; }]>
Renders your own element in place of the default one. Spread the given props onto it.
yearFormat

"numeric" | "2-digit" | ((year: number) => string)
How the year should be formatted in the select options.
years

number[]
An array of years to display in the select. This allows for complete control over which years appear, such as showing only years with data or excluding certain periods.
element Bindable

HTMLElement | null
Bindable reference to the DOM element.

Default null

DateRangePicker.Calendar

children

Snippet<[CalendarRootSnippetProps]>
Content rendered inside.
id

string
Id of the element.
style

string | StyleProperties | null
Inline styles for the element.
element Bindable

HTMLElement | null
Bindable reference to the DOM element.

Default null

DateRangePicker.Input

children

Snippet<[DateRangeFieldInputSnippetProps]>
Content rendered inside.
id

string
Id of the element.
style

string | StyleProperties | null
Inline styles for the element.
form

string
Id of the form the hidden inputs belong to.
type Required

"start" | "end"
Whether this input represents the start or end of the date range.
name

string
The name to use for the hidden input element associated with this input used for form submission.
element Bindable

HTMLElement | null
Bindable reference to the DOM element.

Default null

DateRangePicker.Label

children

Snippet<[]>
Content rendered inside.
id

string
Id of the element.
style

string | StyleProperties | null
Inline styles for the element.
child

Snippet<[{ props: Record<string, unknown>; }]>
Renders your own element in place of the default one. Spread the given props onto it.
element Bindable

HTMLElement | null
Bindable reference to the DOM element.

Default null

DateRangePicker.Trigger

children

Snippet<[]>
Content rendered inside.
id

string
Id of the element.
style

string | StyleProperties | null
Inline styles for the element.
openOnHover

boolean
Whether the popover should open when the trigger is hovered.
openDelay

number
How long to wait before opening the popover on hover (ms). Only applies when openOnHover is true.
closeDelay

number
How long to wait before closing the popover after hover ends (ms). Only applies when openOnHover is true.
element Bindable

HTMLElement | null
Bindable reference to the DOM element.

Default null