Date Field

Enables users to input specific dates within a designated field.

Birthday
mm
dd
yyyy
	<script lang="ts">
  import { DateField } from "bits-ui";
</script>
 
<DateField.Root>
  <div class="flex w-full max-w-[280px] flex-col gap-1.5">
    <DateField.Label class="block select-none text-sm font-medium"
      >Birthday</DateField.Label
    >
    <DateField.Input
      class="flex h-input w-full select-none items-center rounded-input border border-border-input bg-background px-2 py-3 text-sm tracking-[0.01em] text-foreground focus-within:border-border-input-hover focus-within:shadow-date-field-focus hover:border-border-input-hover data-[invalid]:border-destructive "
    >
      {#snippet children({ segments })}
        {#each segments as { part, value }}
          <div class="inline-block select-none">
            {#if part === "literal"}
              <DateField.Segment {part} class="p-1 text-muted-foreground">
                {value}
              </DateField.Segment>
            {:else}
              <DateField.Segment
                {part}
                class="rounded-5px px-1 py-1 hover:bg-muted focus:bg-muted focus:text-foreground focus-visible:!ring-0 focus-visible:!ring-offset-0 aria-[valuetext=Empty]:text-muted-foreground data-[invalid]:text-destructive"
              >
                {value}
              </DateField.Segment>
            {/if}
          </div>
        {/each}
      {/snippet}
    </DateField.Input>
  </div>
</DateField.Root>

Overview

The DateField component is an alternative to the native <input type="date"> element. It provides a more flexible and customizable way to select dates within a designated field.

Before jumping into the DateField component, it's important to understand how dates and times are handled in Bits UI. You can learn more about this on the Dates page.

Structure

	<script lang="ts">
	import { DateField } from "$lib";
</script>
 
<DateField.Root>
	<DateField.Label>Check-in date</DateField.Label>
	<DateField.Input>
		{#snippet children({ segments })}
			{#each segments as { part, value }}
				<DateField.Segment {part}>
					{value}
				</DateField.Segment>
			{/each}
		{/snippet}
	</DateField.Input>
</DateField.Root>

Reusable Components

It's recommended to use the DateField primitives to build your own custom date field component that can be used throughout your application.

The following example shows how you might create a reusable MyDateField component that can be used throughout your application. For style inspiration, reference the featured demo at the top of this page.

MyDateField.svelte
	<script lang="ts">
	import { DateField, type WithoutChildrenOrChild } from "bits-ui";
 
	type Props = WithoutChildrenOrChild<DateField.RootProps> & {
		labelText: string;
	};
 
	let { value, placeholder, name, ...restProps }: Props = $props();
</script>
 
<DateField.Root bind:value bind:placeholder {name} {...restProps}>
	<DateField.Label>{labelText}</DateField.Label>
	<DateField.Input>
		{#snippet children({ segments })}
			{#each segments as { part, value }}
				<DateField.Segment {part}>
					{value}
				</DateField.Segment>
			{/each}
		{/snippet}
	</DateField.Input>
</DateField.Root>
Select a date
mm
dd
yyyy
	<script lang="ts">
  import { DateField } from "bits-ui";
 
  let {
    labelText = "Select a date",
    value = $bindable(),
    placeholder = $bindable(),
    ...restProps
  }: DateField.RootProps & { labelText: string } = $props();
</script>
 
<DateField.Root bind:value bind:placeholder {...restProps}>
  <div class="flex w-fit min-w-[280px] flex-col gap-1.5">
    <DateField.Label class="block select-none text-sm font-medium"
      >{labelText}</DateField.Label
    >
    <DateField.Input
      class="flex h-input w-full select-none items-center rounded-input border border-border-input bg-background px-2 py-3 text-sm tracking-[0.01em] text-foreground focus-within:border-border-input-hover focus-within:shadow-date-field-focus hover:border-border-input-hover data-[invalid]:border-destructive "
    >
      {#snippet children({ segments })}
        {#each segments as { part, value }}
          <div class="inline-block select-none">
            {#if part === "literal"}
              <DateField.Segment {part} class="p-1 text-muted-foreground">
                {value}
              </DateField.Segment>
            {:else}
              <DateField.Segment
                {part}
                class="rounded-5px px-1 py-1 hover:bg-muted focus:bg-muted focus:text-foreground focus-visible:!ring-0 focus-visible:!ring-offset-0 aria-[valuetext=Empty]:text-muted-foreground data-[invalid]:text-destructive"
              >
                {value}
              </DateField.Segment>
            {/if}
          </div>
        {/each}
      {/snippet}
    </DateField.Input>
  </div>
</DateField.Root>

We'll be using this newly created MyDateField component in the following demos and examples to prevent repeating the same code, so be sure to reference it as you go through the documentation.

Segments

A segment of the DateField represents a not only a specific part of the date, such as the day, month, year, hour, but can also reference a "literal" which is typically a separator between the different parts of the date, and varies based on the locale.

Notice that in the MyDateField component we created, we're styling the DateField.Segment components differently based on whether they are a "literal" or not.

Placeholder

The placeholder prop for the DateField.Root component isn't what is displayed when the field is empty, but rather what date our field should start with when the user attempts to cycle through the segments. The placeholder can also be used to set a granularity for the date field, which will determine which type of DateValue object is used for the value.

By default, the placeholder will be set to the current date, and be of type CalendarDate. However, if we wanted this date field to also allow for selecting a time, we could set the placeholder to a CalendarDateTime object.

	<script lang="ts">
	import MyDateField from "$lib/components/MyDateField.svelte";
	import { CalendarDateTime } from "@internationalized/date";
</script>
 
<MyDateField placeholder={new CalendarDateTime(2024, 8, 3, 12, 30)} />
Select a date
mm
dd
yyyy
––
––
PM

If we're collecting a date from the user where we want the timezone as well, we can use a ZonedDateTime object instead.

	<script lang="ts">
	import MyDateField from "$lib/components/MyDateField.svelte";
	import { now, getLocalTimeZone } from "@internationalized/date";
</script>
 
<MyDateField placeholder={now("America/New_York")} />
Select a date
mm
dd
yyyy
––
––
PM
EDT

Managing Placeholder State

Bits UI offers several approaches to manage and synchronize the component's placeholder state, catering to different levels of control and integration needs.

1. Two-Way Binding

For seamless state synchronization, use Svelte's bind:placeholder directive. This method automatically keeps your local state in sync with the component's internal state.

	<script lang="ts">
	import { DateField } from "bits-ui";
	import { CalendarDateTime } from "@internationalized/date";
	let myPlaceholder = $state(new CalendarDateTime(2024, 8, 3, 12, 30));
</script>
 
<button onclick={() => (myPlaceholder = new CalendarDate(2024, 8, 3))}>
	Set placeholder to August 3rd, 2024
</button>
 
<DateField.Root bind:placeholder={myPlaceholder}>
	<!-- ... -->
</DateField.Root>

Key Benefits

  • Simplifies state management
  • Automatically updates myPlaceholder when the internal state changes
  • Allows external control (e.g., changing the placeholder via a separate button/programmatically)

2. Change Handler

For more granular control or to perform additional logic on state changes, use the onPlaceholderChange prop. This approach is useful when you need to execute custom logic alongside state updates.

	<script lang="ts">
	import { DateField } from "bits-ui";
	import { CalendarDateTime } from "@internationalized/date";
	let myPlaceholder = $state(new CalendarDateTime(2024, 8, 3, 12, 30));
</script>
 
<DateField.Root
	placeholder={myPlaceholder}
	onPlaceholderChange={(p) => {
		placeholder = p;
	}}
>
	<!-- ... -->
</DateField.Root>

Use Cases

  • Implementing custom behaviors on placeholder change
  • Integrating with external state management solutions
  • Triggering side effects (e.g., logging, data fetching)

3. Fully Controlled

For complete control over the component's placeholder state, use the controlledPlaceholder prop. This approach requires you to manually manage the state, giving you full control over when and how the component responds to change events.

To implement controlled state:

  1. Set the controlledPlaceholder prop to true on the DateField.Root component.
  2. Provide a placeholder prop to DateField.Root, which should be a variable holding the current state.
  3. Implement an onPlaceholderChange handler to update the state when the internal state changes.
	<script lang="ts">
	import { DateField } from "bits-ui";
	let myPlaceholder = $state();
</script>
 
<DateField.Root
	controlledPlaceholder
	placeholder={myPlaceholder}
	onPlaceholderChange={(p) => (myPlaceholder = p)}
>
	<!-- ... -->
</DateField.Root>

When to Use

  • Implementing complex logic
  • Coordinating multiple UI elements
  • Debugging state-related issues

Managing Value State

Bits UI offers several approaches to manage and synchronize the component's value state, catering to different levels of control and integration needs.

1. Two-Way Binding

For seamless state synchronization, use Svelte's bind:value directive. This method automatically keeps your local state in sync with the component's internal state.

	<script lang="ts">
	import { DateField } from "bits-ui";
	import { CalendarDateTime } from "@internationalized/date";
	let myValue = $state(new CalendarDateTime(2024, 8, 3, 12, 30));
</script>
 
<button onclick={() => (myValue = myValue.add({ days: 1 }))}> Add 1 day </button>
<DateField.Root bind:value={myValue}>
	<!-- ... -->
</DateField.Root>

Key Benefits

  • Simplifies state management
  • Automatically updates myValue when the internal state changes
  • Allows external control (e.g., changing the value via a separate button/programmatically)

2. Change Handler

For more granular control or to perform additional logic on state changes, use the onValueChange prop. This approach is useful when you need to execute custom logic alongside state updates.

	<script lang="ts">
	import { DateField } from "bits-ui";
	import { CalendarDateTime } from "@internationalized/date";
	let myValue = $state(new CalendarDateTime(2024, 8, 3, 12, 30));
</script>
 
<DateField.Root
	value={myValue}
	onValueChange={(v) => {
		value = v.set({ hour: v.hour + 1 });
	}}
>
	<!-- ... -->
</DateField.Root>

Use Cases

  • Implementing custom behaviors on value change
  • Integrating with external state management solutions
  • Triggering side effects (e.g., logging, data fetching)

3. Fully Controlled

For complete control over the component's value state, use the controlledValue prop. This approach requires you to manually manage the state, giving you full control over when and how the component responds to change events.

To implement controlled state:

  1. Set the controlledValue prop to true on the DateField.Root component.
  2. Provide a value prop to DateField.Root, which should be a variable holding the current state.
  3. Implement an onValueChange handler to update the state when the internal state changes.
	<script lang="ts">
	import { DateField } from "bits-ui";
	let myValue = $state();
</script>
 
<DateField.Root controlledValue value={myValue} onValueChange={(v) => (myValue = v)}>
	<!-- ... -->
</DateField.Root>

When to Use

  • Implementing complex logic
  • Coordinating multiple UI elements
  • Debugging state-related issues

Default Value

Often, you'll want to start the DateField.Root component with a default value. Likely this value will come from a database in the format of an ISO 8601 string. You can use the parseDate function from the @internationalized/date package to parse the string into a CalendarDate object.

+page.svelte
	<script lang="ts">
	import { DateField } from "bits-ui";
	import { parseDate } from "@internationalized/date";
 
	// this came from a database/API call
	const date = "2024-08-03";
 
	let value = $state(parseDate(date));
</script>
 
<DateField.Root {value}>
	<!-- ... -->
</DateField.Root>
Select a date
08
03
2024

Now our input is populated with the default value. In addition to the parseDate function, you can also use parseDateTime or parseZonedDateTime to parse the string into a CalendarDateTime or ZonedDateTime object respectively.

Validation

Minimum Value

You can set a minimum value for the DateField.Root component by using the minValue prop. If a user selects a date that is less than the minimum value, the date field will be marked as invalid.

	<script lang="ts">
	import MyDateField from "$lib/components/MyDateField.svelte";
	import { today, getLocalTimeZone } from "@internationalized/date";
 
	const todayDate = today(getLocalTimeZone());
	const yesterday = todayDate.subtract({ days: 1 });
</script>
 
<MyDateField minValue={todayDate} value={yesterday} />
Select a date
10
31
2024

In the example above, we're setting the minimum value to today, and the default value to yesterday. This causes the date field to be marked as invalid, and we can style it accordingly. If you adjust the date to be greater than the minimum value, the invalid state will be cleared.

Maximum Value

You can set a maximum value for the DateField.Root component by using the maxValue prop. If a user selects a date that is greater than the maximum value, the date field will be marked as invalid.

	<script lang="ts">
	import MyDateField from "$lib/components/MyDateField.svelte";
	import { today, getLocalTimeZone } from "@internationalized/date";
 
	const todayDate = today(getLocalTimeZone());
	const tomorrow = todayDate.add({ days: 1 });
</script>
 
<MyDateField maxValue={todayDate} value={tomorrow} />
Select a date
11
02
2024

In the example above, we're setting the maximum value to today, and the default value to tomorrow. This causes the date field to be marked as invalid, and we can style it accordingly. If you adjust the date to be less than the maximum value, the invalid state will be cleared.

Custom Validation

You can use the validate prop to provide a custom validation function for the date field. This function should return a string or array of strings as validation errors if the date is invalid, or undefined/nothing if the date is valid.

The strings are then passed to the onInvalid callback, which you can use to display an error message to the user.

	<script lang="ts">
	import MyDateField from "$lib/components/MyDateField.svelte";
	import { CalendarDate, type DateValue } from "@internationalized/date";
 
	const value = new CalendarDate(2024, 8, 2);
 
	function validate(date: DateValue) {
		return date.day === 1 ? "Date cannot be the first day of the month" : undefined;
	}
 
	function onInvalid(reason: "min" | "max" | "custom", msg?: string | string[]) {
		if (reason === "custom") {
			if (typeof msg === "string") {
				// do something with the error message
				console.log(msg);
				return;
			} else if (Array.isArray(msg)) {
				// do something with the error messages
				console.log(msg);
				return;
			}
			console.log("The date is invalid");
		} else if (reason === "min") {
			// let the user know that the date is too early.
			console.log("The date is too early.");
		} else if (reason === "max") {
			// let the user know that the date is too late.
			console.log("The date is too late.");
		}
	}
</script>
 
<MyDateField {validate} {value} {onInvalid} />
Select a date
08
02
2024

In the example above, we're setting the isDateUnavailable prop to a function that returns true for the first day of the month. Try selecting a date that is the first day of the month to see the date field marked as invalid.

Granularity

The granularity prop sets the granularity of the date field, which determines which segments are rendered in the date field. The granularity can be set to either 'day', 'hour', 'minute', or 'second'.

	<script lang="ts">
	import MyDateField from "$lib/components/MyDateField.svelte";
	import { CalendarDateTime } from "@internationalized/date";
 
	const value = new CalendarDateTime(2024, 8, 2, 12, 30);
</script>
 
<MyDateField granularity="second" {value} />
Select a date
08
02
2024
12
30
00
PM

In the example above, we're setting the granularity to 'second', which means that the date field will include an additional segment for the seconds.

API Reference

DateField.Root

The root date field component.

Property Type Description
value $bindable
DateValue

The selected date.

Default: undefined
onValueChange
function

A function that is called when the selected date changes.

Default: undefined
controlledValue
boolean

Whether or not the value is controlled or not. If true, the component will not update the value state internally, instead it will call onValueChange when it would have otherwise, and it is up to you to update the value prop that is passed to the component.

Default: false
placeholder $bindable
DateValue

The placeholder date, which is used to determine what date to start the segments from when no value exists.

Default: undefined
onPlaceholderChange
function

A function that is called when the placeholder date changes.

Default: undefined
controlledPlaceholder
boolean

Whether or not the placeholder is controlled or not. If true, the component will not update the placeholder state internally, instead it will call onPlaceholderChange when it would have otherwise, and it is up to you to update the value prop that is passed to the component.

Default: false
required
boolean

Whether or not the date field is required.

Default: false
validate
function

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

Default: undefined
onInvalid
function

A callback fired when the date field's value is invalid.

Default: undefined
errorMessageId
string

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

Default: undefined
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
maxValue
DateValue

The maximum valid date that can be entered.

Default: undefined
minValue
DateValue

The minimum valid date that can be entered.

Default: undefined
locale
string

The locale to use for formatting dates.

Default: 'en-US'
disabled
boolean

Whether or not the accordion is disabled.

Default: false
readonly
boolean

Whether or not the field is readonly.

Default: false
readonlySegments
EditableSegmentPart[]

An array of segments that should be readonly, which prevent user input on them.

Default: undefined
children
Snippet

The children content to render.

Default: undefined

DateField.Input

The container for the segments of the date field.

Property Type Description
name
string

The name of the date field used for form submission. If provided, a hidden input element will be rendered alongside the date field.

Default: undefined
ref $bindable
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See Child Snippet docs for more information.

Default: undefined
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.

DateField.Segment

A segment of the date field.

Property Type Description
part required
SegmentPart

The part of the date to render.

Default: undefined
ref $bindable
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See Child Snippet docs for more information.

Default: undefined
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-readonly
''

Present on the element when the field or segment is readonly

data-segment
enum

The part of the date to render.

data-date-field-segment
''

Present on the element.

DateField.Label

The label for the date field.

Property Type Description
ref $bindable
HTMLSpanElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See Child Snippet docs for more information.

Default: undefined
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-label
''

Present on the element.