# Date Range Picker

Segmented start/end date fields and a range calendar popup.

- Package: `@mielui/svelte`
- Component version: `2.0.0`
- Depends on Mielui components: _internal/utils, date-picker, range-calendar, calendar, button, input
- Shared utilities: utils.cn, hugeicons-icon

## Install

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

## API

This reference is generated at build time from the component manifest, public `index.ts`, and documentation examples below. Changes to those source files are reflected here in the published Markdown. Standard Svelte and HTML attributes accepted by the exported prop types are supported.


### Content

| Prop | Type | Default | Required | Bindable | Description |
| --- | --- | --- | --- | --- | --- |
| children | Snippet<[]> \| undefined | - | No | No | Content rendered inside. |
| dir | Direction \| undefined | - | No | No | The text direction of the content. |
| id | string \| undefined | - | No | No | Id of the element. |
| style | string \| StyleProperties \| null \| undefined | - | No | No | Inline styles for the element. |
| align | "center" \| "end" \| "start" \| undefined | 'start' | No | No | The preferred alignment of the anchor to render against when open. This may change when collisions occur. |
| onInteractOutside | InteractOutsideEventHandler \| undefined | - | No | No | 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 \| undefined | - | No | No | 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) \| undefined | - | No | No | Callback fired when focus leaves the dismissible layer. |
| preventScroll | boolean \| undefined | - | No | No | 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) \| undefined | - | No | No | Callback fired when escape is pressed. |
| escapeKeydownBehavior | EscapeBehaviorType \| undefined | - | No | No | 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" \| undefined | - | No | No | The preferred side of the anchor to render against when open. Will be reversed when collisions occur. |
| sideOffset | number \| undefined | 6 | No | No | The distance in pixels from the anchor to the floating element. |
| alignOffset | number \| undefined | - | No | No | An offset in pixels from the "start" or "end" alignment options. |
| arrowPadding | number \| undefined | - | No | No | 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 \| undefined | - | No | No | When `true`, overrides the `side` and `align` options to prevent collisions with the boundary edges. |
| collisionBoundary | Arrayable<Boundary> \| undefined | - | No | No | A boundary element or array of elements to check for collisions against. |
| collisionPadding | number \| Partial<Record<"left" \| "right" \| "top" \| "bottom", number>> \| undefined | 8 | No | No | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision. |
| sticky | "partial" \| "always" \| undefined | - | No | No | Keeps the panel in view while its anchor scrolls. `partial` keeps part of it visible and `always` keeps all of it. |
| hideWhenDetached | boolean \| undefined | - | No | No | Hides the panel when the trigger scrolls out of view. |
| updatePositionStrategy | "optimized" \| "always" \| undefined | - | No | No | "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" \| undefined | - | No | No | The positioning strategy to use for the floating element. |
| customAnchor | string \| HTMLElement \| Measurable \| null \| undefined | - | No | No | 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 \| undefined | - | No | No | Passing `true` will prevent the overflow of text selection outside the element, provided the element is the top layer. |
| onOpenAutoFocus | EventCallback \| undefined | - | No | No | Event handler called when auto-focusing on open. Can be prevented. |
| onCloseAutoFocus | EventCallback \| undefined | - | No | No | Event handler called when auto-focusing on close. Can be prevented. |
| trapFocus | boolean \| undefined | - | No | No | Whether focus is trapped within the focus scope. |
| element | HTMLElement \| null \| undefined | null | No | Yes | Bindable reference to the DOM element. |
| surface | "solid" \| "glass" \| undefined | - | No | No | Surface treatment. Omit it to inherit `--mielui-surface` from the theme. |
| portal | boolean \| undefined | true | No | No | Moves the panel to the end of the document so ancestors cannot clip it. Set false to render it in place. |

Also accepts the native HTML attributes and events listed in the rendered API reference.

### Segment

| Prop | Type | Default | Required | Bindable | Description |
| --- | --- | --- | --- | --- | --- |
| children | Snippet<[]> \| undefined | - | No | No | Content rendered inside. |
| id | string \| undefined | - | No | No | Id of the element. |
| part | "day" \| "dayPeriod" \| "hour" \| "literal" \| "minute" \| "month" \| "second" \| "timeZoneName" \| "year" | - | Yes | No | Which part of the date this segment edits. |
| style | string \| StyleProperties \| null \| undefined | - | No | No | Inline styles for the element. |
| child | Snippet<[{ props: Record<string, unknown>; }]> \| undefined | - | No | No | Renders your own element in place of the default one. Spread the given `props` onto it. |
| element | HTMLElement \| null \| undefined | null | No | Yes | Bindable reference to the DOM element. |

Also accepts the native HTML attributes and events listed in the rendered API reference.

### Cell

| Prop | Type | Default | Required | Bindable | Description |
| --- | --- | --- | --- | --- | --- |
| children | Snippet<[CalendarCellSnippetProps]> \| undefined | - | No | No | Content rendered inside. |
| id | string \| undefined | - | No | No | Id of the element. |
| style | string \| StyleProperties \| null \| undefined | - | No | No | Inline styles for the element. |
| date | CalendarDate \| CalendarDateTime \| ZonedDateTime | - | Yes | No | The date value of the cell. |
| month | CalendarDate \| CalendarDateTime \| ZonedDateTime | - | Yes | No | The month DateValue that this cell is being rendered in. |
| child | Snippet<[CalendarCellSnippetProps & { props: Record<string, unknown>; }]> \| undefined | - | No | No | Renders your own element in place of the default one. Spread the given `props` onto it. |
| element | HTMLElement \| null \| undefined | null | No | Yes | Bindable reference to the DOM element. |

Also accepts the native HTML attributes and events listed in the rendered API reference.

### Day

| Prop | Type | Default | Required | Bindable | Description |
| --- | --- | --- | --- | --- | --- |
| children | Snippet<[CalendarDaySnippetProps]> \| undefined | - | No | No | Content rendered inside. |
| id | string \| undefined | - | No | No | Id of the element. |
| style | string \| StyleProperties \| null \| undefined | - | No | No | Inline styles for the element. |
| child | Snippet<[CalendarDaySnippetProps & { props: Record<string, unknown>; }]> \| undefined | - | No | No | Renders your own element in place of the default one. Spread the given `props` onto it. |
| element | HTMLElement \| null \| undefined | null | No | Yes | Bindable reference to the DOM element. |

Also accepts the native HTML attributes and events listed in the rendered API reference.

### Grid

| Prop | Type | Default | Required | Bindable | Description |
| --- | --- | --- | --- | --- | --- |
| children | Snippet<[]> \| undefined | - | No | No | Content rendered inside. |
| id | string \| undefined | - | No | No | Id of the element. |
| style | string \| StyleProperties \| null \| undefined | - | No | No | Inline styles for the element. |
| child | Snippet<[{ props: Record<string, unknown>; }]> \| undefined | - | No | No | Renders your own element in place of the default one. Spread the given `props` onto it. |
| element | HTMLElement \| null \| undefined | null | No | Yes | Bindable reference to the DOM element. |

Also accepts the native HTML attributes and events listed in the rendered API reference.

### GridBody

| Prop | Type | Default | Required | Bindable | Description |
| --- | --- | --- | --- | --- | --- |
| children | Snippet<[]> \| undefined | - | No | No | Content rendered inside. |
| id | string \| undefined | - | No | No | Id of the element. |
| style | string \| StyleProperties \| null \| undefined | - | No | No | Inline styles for the element. |
| child | Snippet<[{ props: Record<string, unknown>; }]> \| undefined | - | No | No | Renders your own element in place of the default one. Spread the given `props` onto it. |
| element | HTMLElement \| null \| undefined | null | No | Yes | Bindable reference to the DOM element. |

Also accepts the native HTML attributes and events listed in the rendered API reference.

### GridHead

| Prop | Type | Default | Required | Bindable | Description |
| --- | --- | --- | --- | --- | --- |
| children | Snippet<[]> \| undefined | - | No | No | Content rendered inside. |
| id | string \| undefined | - | No | No | Id of the element. |
| style | string \| StyleProperties \| null \| undefined | - | No | No | Inline styles for the element. |
| child | Snippet<[{ props: Record<string, unknown>; }]> \| undefined | - | No | No | Renders your own element in place of the default one. Spread the given `props` onto it. |
| element | HTMLElement \| null \| undefined | null | No | Yes | Bindable reference to the DOM element. |

Also accepts the native HTML attributes and events listed in the rendered API reference.

### GridRow

| Prop | Type | Default | Required | Bindable | Description |
| --- | --- | --- | --- | --- | --- |
| children | Snippet<[]> \| undefined | - | No | No | Content rendered inside. |
| id | string \| undefined | - | No | No | Id of the element. |
| style | string \| StyleProperties \| null \| undefined | - | No | No | Inline styles for the element. |
| child | Snippet<[{ props: Record<string, unknown>; }]> \| undefined | - | No | No | Renders your own element in place of the default one. Spread the given `props` onto it. |
| element | HTMLElement \| null \| undefined | null | No | Yes | Bindable reference to the DOM element. |

Also accepts the native HTML attributes and events listed in the rendered API reference.

### HeadCell

| Prop | Type | Default | Required | Bindable | Description |
| --- | --- | --- | --- | --- | --- |
| children | Snippet<[]> \| undefined | - | No | No | Content rendered inside. |
| id | string \| undefined | - | No | No | Id of the element. |
| style | string \| StyleProperties \| null \| undefined | - | No | No | Inline styles for the element. |
| child | Snippet<[{ props: Record<string, unknown>; }]> \| undefined | - | No | No | Renders your own element in place of the default one. Spread the given `props` onto it. |
| element | HTMLElement \| null \| undefined | null | No | Yes | Bindable reference to the DOM element. |

Also accepts the native HTML attributes and events listed in the rendered API reference.

### Header

| Prop | Type | Default | Required | Bindable | Description |
| --- | --- | --- | --- | --- | --- |
| children | Snippet<[]> \| undefined | - | No | No | Content rendered inside. |
| id | string \| undefined | - | No | No | Id of the element. |
| style | string \| StyleProperties \| null \| undefined | - | No | No | Inline styles for the element. |
| child | Snippet<[{ props: Record<string, unknown>; }]> \| undefined | - | No | No | Renders your own element in place of the default one. Spread the given `props` onto it. |
| element | HTMLElement \| null \| undefined | null | No | Yes | Bindable reference to the DOM element. |

Also accepts the native HTML attributes and events listed in the rendered API reference.

### Heading

| Prop | Type | Default | Required | Bindable | Description |
| --- | --- | --- | --- | --- | --- |
| children | Snippet<[CalendarHeadingSnippetProps]> \| undefined | - | No | No | Content rendered inside. |
| id | string \| undefined | - | No | No | Id of the element. |
| style | string \| StyleProperties \| null \| undefined | - | No | No | Inline styles for the element. |
| child | Snippet<[CalendarHeadingSnippetProps & { props: Record<string, unknown>; }]> \| undefined | - | No | No | Renders your own element in place of the default one. Spread the given `props` onto it. |
| element | HTMLElement \| null \| undefined | null | No | Yes | Bindable reference to the DOM element. |

Also accepts the native HTML attributes and events listed in the rendered API reference.

### Month

| Prop | Type | Default | Required | Bindable | Description |
| --- | --- | --- | --- | --- | --- |
| class | string \| undefined | - | No | No | Classes added to the element. |
| month | { value: DateValue; weeks: DateValue[][]; dates: DateValue[]; } | - | Yes | No | Month data from the Root snippet. |
| weekdays | string[] | - | Yes | No | Weekday names from the Root snippet. |
| locale | string \| undefined | 'en-US' | No | No | BCP 47 locale used for names and number formats. |
| showHeading | boolean \| undefined | false | No | No | Shows the month name above the grid, for layouts with several months. |
| day | Snippet<[date: DateValue]> \| undefined | - | No | No | Custom content for each day cell. |



### MonthSelect

| Prop | Type | Default | Required | Bindable | Description |
| --- | --- | --- | --- | --- | --- |
| children | Snippet<[CalendarMonthSelectSnippetProps]> \| undefined | - | No | No | Content rendered inside. |
| id | string \| undefined | - | No | No | Id of the element. |
| style | string \| StyleProperties \| null \| undefined | - | No | No | Inline styles for the element. |
| child | Snippet<[CalendarMonthSelectSnippetProps & { props: Record<string, unknown>; }]> \| undefined | - | No | No | 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) \| undefined | - | No | No | How the month names should be formatted in the select options. |
| months | number[] \| undefined | - | No | No | 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 | HTMLElement \| null \| undefined | null | No | Yes | Bindable reference to the DOM element. |

Also accepts the native HTML attributes and events listed in the rendered API reference.

### NextButton

| Prop | Type | Default | Required | Bindable | Description |
| --- | --- | --- | --- | --- | --- |
| children | Snippet<[]> \| undefined | - | No | No | Content rendered inside. |
| id | string \| undefined | - | No | No | Id of the element. |
| style | string \| StyleProperties \| null \| undefined | - | No | No | Inline styles for the element. |
| child | Snippet<[{ props: Record<string, unknown>; }]> \| undefined | - | No | No | Renders your own element in place of the default one. Spread the given `props` onto it. |
| element | HTMLElement \| null \| undefined | null | No | Yes | Bindable reference to the DOM element. |

Also accepts the native HTML attributes and events listed in the rendered API reference.

### PrevButton

| Prop | Type | Default | Required | Bindable | Description |
| --- | --- | --- | --- | --- | --- |
| children | Snippet<[]> \| undefined | - | No | No | Content rendered inside. |
| id | string \| undefined | - | No | No | Id of the element. |
| style | string \| StyleProperties \| null \| undefined | - | No | No | Inline styles for the element. |
| child | Snippet<[{ props: Record<string, unknown>; }]> \| undefined | - | No | No | Renders your own element in place of the default one. Spread the given `props` onto it. |
| element | HTMLElement \| null \| undefined | null | No | Yes | Bindable reference to the DOM element. |

Also accepts the native HTML attributes and events listed in the rendered API reference.

### YearSelect

| Prop | Type | Default | Required | Bindable | Description |
| --- | --- | --- | --- | --- | --- |
| children | Snippet<[CalendarYearSelectSnippetProps]> \| undefined | - | No | No | Content rendered inside. |
| id | string \| undefined | - | No | No | Id of the element. |
| style | string \| StyleProperties \| null \| undefined | - | No | No | Inline styles for the element. |
| child | Snippet<[CalendarYearSelectSnippetProps & { props: Record<string, unknown>; }]> \| undefined | - | No | No | Renders your own element in place of the default one. Spread the given `props` onto it. |
| yearFormat | "numeric" \| "2-digit" \| ((year: number) => string) \| undefined | - | No | No | How the year should be formatted in the select options. |
| years | number[] \| undefined | - | No | No | 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 | HTMLElement \| null \| undefined | null | No | Yes | Bindable reference to the DOM element. |

Also accepts the native HTML attributes and events listed in the rendered API reference.

### Root

| Prop | Type | Default | Required | Bindable | Description |
| --- | --- | --- | --- | --- | --- |
| children | Snippet<[]> \| undefined | - | No | No | Content rendered inside. |
| id | string \| undefined | - | No | No | Id of the element. |
| placeholder | DateValue \| undefined | - | No | Yes | 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 \| undefined | - | No | No | Inline styles for the element. |
| disabled | boolean \| undefined | false | No | No | 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. |
| value | DateRange \| undefined | - | No | Yes | The value of the date picker. |
| readonly | boolean \| undefined | false | No | No | If true, the date field will be readonly, and users will not be able to edit the values of any of the individual segments. |
| required | boolean \| undefined | false | No | No | Whether or not the hidden input of the date field requires a value to be submitted. |
| onValueChange | OnChangeFn<DateRange> \| undefined | - | No | No | A callback function called when the value changes. |
| onPlaceholderChange | OnChangeFn<DateValue> \| undefined | - | No | No | A callback function called when the placeholder value changes. |
| preventDeselect | boolean \| undefined | - | No | No | Whether or not users can deselect a date once selected without selecting another date. |
| minValue | DateValue \| undefined | - | No | No | 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 \| undefined | - | No | No | 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 \| undefined | - | No | No | Applicable only when `numberOfMonths` is greater than 1. |
| weekStartsOn | WeekStartsOn \| undefined | - | No | No | 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" \| undefined | 'short' | No | No | How the string representation of the weekdays provided via the `weekdays` state store should be formatted. |
| isDateDisabled | DateMatcher \| undefined | - | No | No | A function that returns true if the given date is disabled, which makes the date unable to be selected in the calendar. |
| isDateUnavailable | DateMatcher \| undefined | - | No | No | A function that returns true if the given date is unavailable, where if selected, the date field will be marked as invalid. |
| fixedWeeks | boolean \| undefined | true | No | No | 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. |
| numberOfMonths | number \| undefined | - | No | No | Determines the number of months to display on the calendar simultaneously. For navigation between months, refer to the `pagedNavigation` prop. |
| calendarLabel | string \| undefined | - | No | No | 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 \| undefined | 'en-US' | No | No | The locale to use for formatting the date field. |
| disableDaysOutsideMonth | boolean \| undefined | true | No | No | 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. |
| maxDays | number \| undefined | - | No | No | The maximum number of days that can be selected in a range. |
| monthFormat | "numeric" \| "long" \| "short" \| "narrow" \| "2-digit" \| ((month: number) => string) \| undefined | - | No | No | The format of the month names in the calendar. |
| yearFormat | "numeric" \| "2-digit" \| ((year: number) => string) \| undefined | - | No | No | The format of the year names in the calendar. |
| open | boolean \| undefined | false | No | Yes | The open state of the date picker popover. |
| onOpenChange | OnChangeFn<boolean> \| undefined | - | No | No | A callback function called when the open state changes. |
| onOpenChangeComplete | OnChangeFn<boolean> \| undefined | - | No | No | A callback function called when the open state changes complete. |
| validate | DateRangeValidator \| undefined | - | No | No | 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 \| undefined | - | No | No | 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")[] \| undefined | - | No | No | An array of segment names that should be readonly. If provided, only the segments not in this array will be editable. |
| hourCycle | 12 \| 24 \| undefined | - | No | No | 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 \| undefined | - | No | No | 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 \| undefined | - | No | No | Whether or not to hide the timeZoneName segment from the date field. |
| errorMessageId | string \| undefined | - | No | No | The `id` of the element which contains the error messages for the date field when the date is invalid. |
| closeOnRangeSelect | boolean \| undefined | - | No | No | Whether to close the popover when a date range is selected. |
| onStartValueChange | OnChangeFn<DateValue \| undefined> \| undefined | - | No | No | 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> \| undefined | - | No | No | 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 \| undefined | - | No | No | The minimum number of days that can be selected in a range. |
| excludeDisabled | boolean \| undefined | - | No | No | 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 | HTMLElement \| null \| undefined | null | No | Yes | Bindable reference to the DOM element. |
| labels | DatePickerLabels \| undefined | - | No | No | Overrides the built-in text and accessible names. Every key is optional and English is the fallback. |

Also accepts the native HTML attributes and events listed in the rendered API reference.

### Calendar

| Prop | Type | Default | Required | Bindable | Description |
| --- | --- | --- | --- | --- | --- |
| children | Snippet<[CalendarRootSnippetProps]> \| undefined | - | No | No | Content rendered inside. |
| id | string \| undefined | - | No | No | Id of the element. |
| style | string \| StyleProperties \| null \| undefined | - | No | No | Inline styles for the element. |
| element | HTMLElement \| null \| undefined | null | No | Yes | Bindable reference to the DOM element. |

Also accepts the native HTML attributes and events listed in the rendered API reference.

### Input

| Prop | Type | Default | Required | Bindable | Description |
| --- | --- | --- | --- | --- | --- |
| children | Snippet<[DateRangeFieldInputSnippetProps]> \| undefined | - | No | No | Content rendered inside. |
| id | string \| undefined | - | No | No | Id of the element. |
| style | string \| StyleProperties \| null \| undefined | - | No | No | Inline styles for the element. |
| form | string \| undefined | - | No | No | Id of the form the hidden inputs belong to. |
| type | "start" \| "end" | - | Yes | No | Whether this input represents the start or end of the date range. |
| name | string \| undefined | - | No | No | The name to use for the hidden input element associated with this input used for form submission. |
| element | HTMLElement \| null \| undefined | null | No | Yes | Bindable reference to the DOM element. |

Also accepts the native HTML attributes and events listed in the rendered API reference.

### Label

| Prop | Type | Default | Required | Bindable | Description |
| --- | --- | --- | --- | --- | --- |
| children | Snippet<[]> \| undefined | - | No | No | Content rendered inside. |
| id | string \| undefined | - | No | No | Id of the element. |
| style | string \| StyleProperties \| null \| undefined | - | No | No | Inline styles for the element. |
| child | Snippet<[{ props: Record<string, unknown>; }]> \| undefined | - | No | No | Renders your own element in place of the default one. Spread the given `props` onto it. |
| element | HTMLElement \| null \| undefined | null | No | Yes | Bindable reference to the DOM element. |

Also accepts the native HTML attributes and events listed in the rendered API reference.

### Trigger

| Prop | Type | Default | Required | Bindable | Description |
| --- | --- | --- | --- | --- | --- |
| children | Snippet<[]> \| undefined | - | No | No | Content rendered inside. |
| id | string \| undefined | - | No | No | Id of the element. |
| style | string \| StyleProperties \| null \| undefined | - | No | No | Inline styles for the element. |
| openOnHover | boolean \| undefined | - | No | No | Whether the popover should open when the trigger is hovered. |
| openDelay | number \| undefined | - | No | No | How long to wait before opening the popover on hover (ms). Only applies when `openOnHover` is `true`. |
| closeDelay | number \| undefined | - | No | No | How long to wait before closing the popover after hover ends (ms). Only applies when `openOnHover` is `true`. |
| element | HTMLElement \| null \| undefined | null | No | Yes | Bindable reference to the DOM element. |

Also accepts the native HTML attributes and events listed in the rendered API reference.

### Public types

~~~~ts
import type { WithElement } from '@mielui/svelte/utils';
import type { DateRangePicker as DatePickerPrimitive } from 'bits-ui';
import type { DatePickerLabels } from '../date-picker/context';

export type DateRangePickerLabels = DatePickerLabels;

export type DateRangePickerProps = WithElement<Omit<DatePickerPrimitive.RootProps, 'child'>> & {
    /**
     * Overrides the built-in text and accessible names. Every key is optional and English is the
     * fallback.
     */
    labels?: DateRangePickerLabels;
};

export { default as Content } from '../date-picker/date-picker-content.svelte';
export { default as Segment } from '../date-picker/date-picker-segment.svelte';
export {
    Cell,
    Day,
    Grid,
    GridBody,
    GridHead,
    GridRow,
    HeadCell,
    Header,
    Heading,
    Month,
    MonthSelect,
    NextButton,
    PrevButton,
    YearSelect
} from '../range-calendar';
export { default as Root } from './date-range-picker.svelte';
export { default as Calendar } from './date-range-picker-calendar.svelte';
export { default as Input } from './date-range-picker-input.svelte';
export { default as Label } from './date-range-picker-label.svelte';
export { default as Trigger } from './date-range-picker-trigger.svelte';
~~~~

## Examples

### Disabled

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

<DateRangePicker.Root disabled placeholder={new CalendarDate(2026, 9, 17)}>
    <div class="grid w-full max-w-lg gap-2">
        <DateRangePicker.Label>Dates are locked</DateRangePicker.Label>
        <div class="flex flex-wrap items-center gap-2">
            <DateRangePicker.Input name="lockedStart" type="start" aria-label="Start date" />
            <DateRangePicker.Input name="lockedEnd" type="end" aria-label="End date" />
            <DateRangePicker.Trigger />
        </div>
    </div>
    <DateRangePicker.Content align="end">
        <DateRangePicker.Calendar />
    </DateRangePicker.Content>
</DateRangePicker.Root>
~~~~

### Events

~~~~svelte
<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
    });
    let start = $state('not picked');
    let end = $state('not picked');
</script>

<div class="flex w-full max-w-lg flex-col gap-3">
    <DateRangePicker.Root
        bind:value
        calendarLabel="Report period"
        closeOnRangeSelect={false}
        onStartValueChange={(date) => {
            start = date?.toString() ?? 'not picked';
        }}
        onEndValueChange={(date) => {
            end = date?.toString() ?? 'not picked';
        }}
    >
        <div class="grid gap-2">
            <DateRangePicker.Label>Report period</DateRangePicker.Label>
            <div class="flex flex-wrap items-center gap-2">
                <DateRangePicker.Input type="start" name="from" aria-label="From" />
                <DateRangePicker.Input type="end" name="to" aria-label="To" />
                <DateRangePicker.Trigger />
            </div>
        </div>
        <DateRangePicker.Content align="end">
            <DateRangePicker.Calendar />
        </DateRangePicker.Content>
    </DateRangePicker.Root>
    <p class="text-sm text-foreground-muted">From {start}. To {end}.</p>
</div>
~~~~

### Exclude Disabled

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

<div class="w-full max-w-lg">
    <DateRangePicker.Root
        calendarLabel="Time off"
        placeholder={new CalendarDate(2026, 9, 1)}
        isDateDisabled={(date) => isWeekend(date, 'en-US')}
        excludeDisabled
    >
        <div class="grid gap-2">
            <DateRangePicker.Label>Time off</DateRangePicker.Label>
            <div class="flex flex-wrap items-center gap-2">
                <DateRangePicker.Input type="start" name="first" aria-label="First day" />
                <DateRangePicker.Input type="end" name="last" aria-label="Last day" />
                <DateRangePicker.Trigger />
            </div>
        </div>
        <DateRangePicker.Content align="end">
            <DateRangePicker.Calendar />
        </DateRangePicker.Content>
    </DateRangePicker.Root>
</div>
~~~~

### Form

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

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

<form
    class="grid w-full max-w-lg gap-3"
    onsubmit={(event) => {
        event.preventDefault();
        const entries = Array.from(new FormData(event.currentTarget).entries());

        submitted = entries
            .map(([name, entry]) => {
                return `${name}=${entry}`;
            })
            .join(', ');
        readonly = true;
    }}
    onreset={() => {
        submitted = '';
        readonly = false;
    }}
>
    <DateRangePicker.Root
        bind:value
        required
        {readonly}
        placeholder={new CalendarDate(2026, 9, 17)}
        minValue={new CalendarDate(2026, 9, 1)}
        maxValue={new CalendarDate(2026, 12, 31)}
    >
        <div class="grid gap-2">
            <DateRangePicker.Label>Travel dates</DateRangePicker.Label>
            <div class="flex flex-wrap items-center gap-2">
                <DateRangePicker.Input type="start" name="arrival" aria-label="Arrival" />
                <DateRangePicker.Input type="end" name="departure" aria-label="Departure" />
                <DateRangePicker.Trigger />
            </div>
        </div>
        <DateRangePicker.Content align="end">
            <DateRangePicker.Calendar />
        </DateRangePicker.Content>
    </DateRangePicker.Root>
    <p class="text-sm text-foreground-muted">
        Choose both dates between September and December 2026. Saving makes the field read-only.
    </p>
    <div class="flex gap-2">
        <Button type="submit" size="sm">Save dates</Button>
        <Button type="reset" variant="outline" size="sm">Reset</Button>
    </div>
    <p role="status" class="min-h-5 text-sm text-foreground-muted">
        {submitted || 'No date submitted.'}
    </p>
</form>
~~~~

### Hero

~~~~svelte
<script lang="ts">
    import { CalendarDate, 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: new CalendarDate(2026, 9, 17),
        end: new CalendarDate(2026, 9, 23)
    });
</script>

<div class="w-full max-w-lg">
    <DateRangePicker.Root bind:value calendarLabel="Travel dates">
        <div class="grid gap-2">
            <DateRangePicker.Label>Travel dates</DateRangePicker.Label>
            <div class="flex flex-wrap items-center gap-2">
                <DateRangePicker.Input type="start" name="startDate" aria-label="Start date" />
                <DateRangePicker.Input type="end" name="endDate" aria-label="End date" />
                <DateRangePicker.Trigger />
            </div>
            <p class="text-sm text-foreground-muted">
                Choose a start and end date, or edit each field.
            </p>
        </div>
        <DateRangePicker.Content align="end">
            <DateRangePicker.Calendar />
        </DateRangePicker.Content>
    </DateRangePicker.Root>
</div>
~~~~

### Range Length

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

<DateRangePicker.Root minDays={3} maxDays={14} placeholder={new CalendarDate(2026, 9, 17)}>
    <div class="grid w-full max-w-lg gap-2">
        <DateRangePicker.Label>Stay</DateRangePicker.Label>
        <div class="flex flex-wrap items-center gap-2">
            <DateRangePicker.Input type="start" name="checkIn" aria-label="Check in" />
            <DateRangePicker.Input type="end" name="checkOut" aria-label="Check out" />
            <DateRangePicker.Trigger />
        </div>
        <p class="text-sm text-foreground-muted">Stays run from 3 to 14 days.</p>
    </div>
    <DateRangePicker.Content align="end">
        <DateRangePicker.Calendar />
    </DateRangePicker.Content>
</DateRangePicker.Root>
~~~~

### Two Months

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

<DateRangePicker.Root
    numberOfMonths={2}
    pagedNavigation
    placeholder={new CalendarDate(2026, 9, 17)}
>
    <div class="grid w-full max-w-lg gap-2">
        <DateRangePicker.Label>Booking dates</DateRangePicker.Label>
        <div class="flex flex-wrap items-center gap-2">
            <DateRangePicker.Input type="start" name="arrival" aria-label="Arrival" />
            <DateRangePicker.Input type="end" name="departure" aria-label="Departure" />
            <DateRangePicker.Trigger />
        </div>
    </div>
    <DateRangePicker.Content align="end">
        <DateRangePicker.Calendar />
    </DateRangePicker.Content>
</DateRangePicker.Root>
~~~~

For the rendered reference, visit [/docs/components/date-range-picker](/docs/components/date-range-picker).