Report an issue

Date Field

Enables users to input specific dates within a designated field.

Birthday
mm
dd
yyyy
	<script lang="ts">
  import { CalendarDate } from "@internationalized/date";
  import { DateField } from "bits-ui";
</script>
 
<DateField.Root minValue={new CalendarDate(2024, 8, 1)}>
  <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>
  • add docs about leap years/birthdays and placeholder date

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>

We'll be using the following MyDateField component in the following demos and examples to prevent repeating the same code over and over.

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-full max-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>

API Reference

DateField.Root

The root date field component.

Property Type Description
value bindable prop
DateValue

The selected date.

Default: undefined
onValueChange
function

A function that is called when the selected date changes.

Default: undefined
placeholder bindable prop
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
required
boolean

Whether or not the date field is required.

Default: false
isDateUnavailable
function

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

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
array

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 prop
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 delegation 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 prop
SegmentPart

The part of the date to render.

Default: undefined
ref bindable prop
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 delegation 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 prop
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 delegation 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.