Report an issue

Date Picker

Facilitates the selection of dates through an input and calendar-based interface.

Structure

	<script lang="ts">
	import { DatePicker } from "bits-ui";
</script>
 
<DatePicker.Root>
	<DatePicker.Label />
	<DatePicker.Input let:segments>
		{#each segments as { part, value }}
			<DatePicker.Segment {part}>
				{value}
			</DatePicker.Segment>
		{/each}
		<DatePicker.Trigger />
	</DatePicker.Input>
	<DatePicker.Content>
		<DatePicker.Calendar let:months let:weekdays>
			<DatePicker.Header>
				<DatePicker.PrevButton />
				<DatePicker.Heading />
				<DatePicker.NextButton />
			</DatePicker.Header>
			{#each months as month}
				<DatePicker.Grid>
					<DatePicker.GridHead>
						<DatePicker.GridRow>
							{#each weekdays as day}
								<DatePicker.HeadCell>
									{day}
								</DatePicker.HeadCell>
							{/each}
						</DatePicker.GridRow>
					</DatePicker.GridHead>
					<DatePicker.GridBody>
						{#each month.weeks as weekDates}
							<DatePicker.GridRow>
								{#each weekDates as date}
									<DatePicker.Cell {date}>
										<DatePicker.Day {date} month={month.value} />
									</DatePicker.Cell>
								{/each}
							</DatePicker.GridRow>
						{/each}
					</DatePicker.GridBody>
				</DatePicker.Grid>
			{/each}
		</DatePicker.Calendar>
	</DatePicker.Content>
</DatePicker.Root>

API Reference

DatePicker.Root

The root date picker component.

Property Type Description
value
DateValue

The selected date.

Default:  —— undefined
onValueChange
function

A function that is called when the selected date changes.

Default:  —— undefined
placeholder
DateValue

The placeholder date, which is used to determine what month to display when no date is selected. This updates as the user navigates the calendar, and can be used to programatically control the calendar's view.

Default:  —— undefined
onPlaceholderChange
function

A function that is called when the placeholder date changes.

Default:  —— undefined
pagedNavigation
boolean

Whether or not to use paged navigation for the calendar. Paged navigation causes the previous and next buttons to navigate by the number of months displayed at once, rather than by one month.

Default: false
preventDeselect
boolean

Whether or not to prevent the user from deselecting a date without selecting another date first.

Default: false
weekStartsOn
number

The day of the week to start the calendar on. 0 is Sunday, 1 is Monday, etc.

Default: 0
weekdayFormat
enum

The format to use for the weekday strings provided via the weekdays slot prop.

Default: 'narrow'
calendarLabel
string

The accessible label for the calendar.

Default:  —— undefined
fixedWeeks
boolean

Whether or not to always display 6 weeks in the calendar.

Default: false
isDateDisabled
function

A function that returns whether or not a date is disabled.

Default:  —— undefined
isDateUnavailable
function

A function that returns whether or not a date is unavailable.

Default:  —— undefined
maxValue
DateValue

The maximum date that can be selected.

Default:  —— undefined
minValue
DateValue

The minimum date that can be selected.

Default:  —— undefined
locale
string

The locale to use for formatting dates.

Default:  —— undefined
multiple
boolean

Whether or not multiple dates can be selected.

Default: false
numberOfMonths
number

The number of months to display at once.

Default: 1
disabled
boolean

Whether or not the accordion is disabled.

Default: false
readonly
boolean

Whether or not the calendar is readonly.

Default: false
hourCycle
enum

The hour cycle to use for formatting times. Defaults to the locale preference

Default:  —— undefined
granularity
enum

The granularity to use for formatting the field. Defaults to 'day' if a CalendarDate is provided, otherwise defaults to 'minute'. The field will render segments for each part of the date up to and including the specified granularity.

Default:  —— undefined
hideTimeZone
boolean

Whether or not to hide the time zone segment of the field.

Default: false
validationId
string

The id of your validation message element, if any, which will be applied to the aria-describedby attribute of the appropriate elements when a validation error occurs.

Default:  —— undefined
descriptionId
string

The id of your description element, if any, which will be applied to the aria-describedby attribute of the appropriate elements.

Default:  —— undefined
disableFocusTrap
boolean

Whether or not to disable the focus trap that is applied to the popover when it's open.

Default: false
preventScroll
boolean

Whether or not to prevent scrolling the body while the popover is open.

Default: false
closeOnOutsideClick
boolean

Whether or not to close the popover when clicking outside of it.

Default: true
closeOnEscape
boolean

Whether or not to close the popover when pressing the escape key.

Default: true
open
boolean

The open state of the link popover component.

Default: false
onOpenChange
function

A callback that fires when the open state changes.

Default:  —— undefined
openFocus
FocusProp

Override the focus when the popover is opened.

Default:  —— undefined
closeFocus
FocusProp

Override the focus when the popover is closed.

Default:  —— undefined
portal
union

Where to render the popover when it is open. Defaults to the body. Can be disabled by passing null

Default:  —— undefined
onOutsideClick
function

A callback function called when a click occurs outside of the element. If event.preventDefault() is called, the default behavior of closing the element will be prevented.

Default:  —— undefined
Slot Property Type Description
months
Month[]

The current months to display in the calendar. Used to render the calendar.

weekdays
string[]

The days of the week to display in the calendar, typically used within the table header.

builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.

Data Attribute Value Description
data-invalid
——

Present on the root element when the calendar is invalid.

data-disabled
——

Present on the root element when the calendar is disabled.

data-readonly
——

Present on the root element when the calendar is readonly.

data-calendar-root
——

Present on the root element.

DatePicker.Label

The label for the date field.

Property Type Description
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLSpanElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.

Data Attribute Value Description
data-invalid
——

Present on the element when the field is invalid

data-date-field-label
——

Present on the element.

DatePicker.Input

The field input component which contains the segments of the date field.

Property Type Description
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.

segments
array

An array of objects used to render the segments of the date field.

Data Attribute Value Description
data-invalid
——

Present on the element when the field is invalid.

data-disabled
——

Present on the element when the field is disabled.

data-date-field-input
——

Present on the element.

DatePicker.Segment

A segment of the date field.

Property Type Description
part
*
Required
SegmentPart

The part of the date to render.

Default:  —— undefined
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.

Data Attribute Value Description
data-invalid
——

Present on the element when the field is invalid

data-disabled
——

Present on the element when the field is disabled

data-segment
enum

The type of segment the element represents.

data-date-field-segment
——

Present on the element.

DatePicker.Trigger

A component which toggles the opening and closing of the popover on press.

Property Type Description
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLButtonElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.

Data Attribute Value Description
data-state
enum

The open state of the link preview.

data-popover-trigger
——

Present on the trigger element.

DatePicker.Content

The contents of the popover which are displayed when the popover is open.

Property Type Description
transition
function

A Svelte transition function to use when transitioning the content in and out.

Default:  —— undefined
transitionConfig
TransitionConfig

The configuration to apply to the transition.

Default:  —— undefined
inTransition
function

A Svelte transition function to use when transitioning the content in and out.

Default:  —— undefined
inTransitionConfig
TransitionConfig

The configuration to apply to the transition.

Default:  —— undefined
outTransition
function

A Svelte transition function to use when transitioning the content in and out.

Default:  —— undefined
outTransitionConfig
TransitionConfig

The configuration to apply to the transition.

Default:  —— undefined
side
enum

The preferred side of the anchor to render against when open. Will be reversed when collisions occur. Floating UI reference.

Default:  —— undefined
sideOffset
number

The amount of offset to apply to the menu's position on the x-axis. Floating UI reference.

Default: 0
align
enum

The preferred alignment of the anchor to render against when open. Floating UI reference.

Default:  —— undefined
alignOffset
number

An offset in pixels from the 'start' or 'end' alignment options. Floating UI reference.

Default: 0
avoidCollisions
boolean

When true, overrides the side and align options to prevent collisions with the boundary edges. Floating UI reference.

Default: true
collisionBoundary
union

A boundary element or array of elements to check for collisions against. Floating UI reference.

Default:  —— undefined
collisionPadding
number

The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision. Floating UI reference.

Default: 0
fitViewport
boolean

Whether the floating element should be constrained to the viewport. Floating UI reference.

Default: false
sameWidth
boolean

Whether the content should be the same width as the trigger. Floating UI reference.

Default: false
strategy
enum

The positioning strategy to use for the floating element. Floating UI reference.

Default: absolute
overlap
boolean

Whether the floating element can overlap the reference element. Floating UI reference.

Default: false
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.

Data Attribute Value Description
data-state
enum

The open state of the popover.

data-popover-content
——

Present on the content element.

DatePicker.Calendar

The calendar component containing the grids of dates.

Slot Property Type Description
months
Month[]

The current months to display in the calendar. Used to render the calendar.

weekdays
string[]

The days of the week to display in the calendar, typically used within the table header.

builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.

Data Attribute Value Description
data-invalid
——

Present on the root element when the calendar is invalid.

data-disabled
——

Present on the root element when the calendar is disabled.

data-readonly
——

Present on the root element when the calendar is readonly.

data-calendar-root
——

Present on the root element.

DatePicker.Header

The header of the calendar.

Property Type Description
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
attrs
object

Additional attributes to apply to the element if using the asChild prop with delegation.

Data Attribute Value Description
data-calendar-header
——

Present on the header element.

DatePicker.PrevButton

The previous button of the calendar.

Property Type Description
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLButtonElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.

Data Attribute Value Description
data-calendar-prev-button
——

Present on the prev button element.

DatePicker.Heading

The heading of the calendar.

Property Type Description
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.

headingValue
string

The heading value.

Data Attribute Value Description
data-calendar-heading
——

Present on the heading element.

DatePicker.NextButton

The next button of the calendar.

Property Type Description
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLButtonElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.

Data Attribute Value Description
data-calendar-next-button
——

Present on the next button element.

DatePicker.Grid

The grid of dates in the calendar, typically representing a month.

Property Type Description
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLTableElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.

Data Attribute Value Description
data-calendar-grid
——

Present on the grid element.

DatePicker.GridRow

A row in the grid of dates in the calendar.

Property Type Description
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLTableRowElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
attrs
object

Additional attributes to apply to the element if using the asChild prop with delegation.

Data Attribute Value Description
data-calendar-grid-row
——

Present on the grid row element.

DatePicker.GridHead

The head of the grid of dates in the calendar.

Property Type Description
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLTableSectionElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
attrs
object

Additional attributes to apply to the element if using the asChild prop with delegation.

Data Attribute Value Description
data-calendar-grid-head
——

Present on the grid head element.

DatePicker.HeadCell

A cell in the head of the grid of dates in the calendar.

Property Type Description
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLTableCellElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
attrs
object

Additional attributes to apply to the element if using the asChild prop with delegation.

Data Attribute Value Description
data-calendar-head-cell
——

Present on the head cell element.

DatePicker.GridBody

The body of the grid of dates in the calendar.

Property Type Description
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLTableSectionElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
attrs
object

Additional attributes to apply to the element if using the asChild prop with delegation.

Data Attribute Value Description
data-calendar-grid-body
——

Present on the grid body element.

DatePicker.Cell

A cell in the calendar grid.

Property Type Description
date
DateValue

The date for the cell.

Default:  —— undefined
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLTableCellElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
attrs
object

Additional attributes to apply to the element if using the asChild prop with delegation.

Data Attribute Value Description
data-disabled
——

Present on the element when the date is disabled.

data-calendar-cell
——

Present on the cell element.

DatePicker.Day

A day in the calendar grid.

Property Type Description
date
DateValue

The date for the cell.

Default:  —— undefined
month
DateValue

The current month the date is being displayed in.

Default:  —— undefined
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
disabled
boolean

Whether or not the date is disabled.

unavailable
boolean

Whether or not the date is unavailable.

selected
boolean

Whether or not the date is selected.

builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.

Data Attribute Value Description
data-disabled
——

Present on the element when the date is disabled.

data-selected
——

Present on the element when the date is selected.

data-unavailable
——

Present on the element when the date is unavailable.

data-value
——

The date in the format "YYYY-MM-DD".

data-today
——

Present on the element when the date is today.

data-outside-month
——

Present on the element when the date is outside the current month.

data-outside-visible-months
——

Present on the element when the date is outside the visible months.

data-focused
——

Present on the element when the date is focused.

data-calendar-day
——

Present on the day element.