Date Picker

A datepicker allows users to enter a date either through text input, or by choosing a date from the calendar.

Good to know: The date picker machine is built on top of the @internationalized/date library.

1.26.4 (latest)Visualize Logic View Source

S	M	T	W	T	F	S
28	29	30	1	2	3	4
5	6	7	8	9	10	11
12	13	14	15	16	17	18
19	20	21	22	23	24	25
26	27	28	29	30	31	1

Features

Displays a calendar view for date selection
Support for date range selection
Support for disabling specific dates
Localization support
Provides keyboard accessibility for navigating the calendar.

Installation

To use the date-picker machine in your project, run the following command in your command line:

npm install @zag-js/date-picker @zag-js/react
# or
yarn add @zag-js/date-picker @zag-js/react

npm install @zag-js/date-picker @zag-js/solid
# or
yarn add @zag-js/date-picker @zag-js/solid

npm install @zag-js/date-picker @zag-js/vue
# or
yarn add @zag-js/date-picker @zag-js/vue

npm install @zag-js/date-picker @zag-js/svelte
# or
yarn add @zag-js/date-picker @zag-js/svelte

Anatomy

To set up the date-picker correctly, you'll need to understand its anatomy and how we name its parts.

Each part includes a data-part attribute to help identify them in the DOM.

Usage

First, import the date picker package into your project

import * as datepicker from "@zag-js/date-picker"

The date picker package exports these key functions:

machine — The state machine logic for the date-picker widget.
connect — The function that translates the machine's state to JSX attributes and event handlers.
parse - The function that parses the date string into a date object. Requires passing the ISO 8601 date format as the first argument.

You'll also need to provide a unique id to the useMachine hook. This is used to ensure that every part has a unique identifier.

Next, import the required hooks and functions for your framework and use the date-picker machine in your project 🔥

import * as datepicker from "@zag-js/date-picker"
import { useMachine, normalizeProps, Portal } from "@zag-js/react"
import { useId } from "react"

function DatePicker() {
  const service = useMachine(datepicker.machine, { id: useId() })

  const api = datepicker.connect(service, normalizeProps)

  return (
    <>
      <div {...api.getControlProps()}>
        <input {...api.getInputProps()} />
        <button {...api.getTriggerProps()}>🗓</button>
      </div>

      <Portal>
        <div {...api.getPositionerProps()}>
          <div {...api.getContentProps()}>
            {/*  Day View  */}
            <div hidden={api.view !== "day"}>
              <div {...api.getViewControlProps({ view: "year" })}>
                <button {...api.getPrevTriggerProps()}>Prev</button>
                <button {...api.getViewTriggerProps()}>
                  {api.visibleRangeText.start}
                </button>
                <button {...api.getNextTriggerProps()}>Next</button>
              </div>

              <table {...api.getTableProps({ view: "day" })}>
                <thead {...api.getTableHeaderProps({ view: "day" })}>
                  <tr {...api.getTableRowProps({ view: "day" })}>
                    {api.weekDays.map((day, i) => (
                      <th scope="col" key={i} aria-label={day.long}>
                        {day.narrow}
                      </th>
                    ))}
                  </tr>
                </thead>
                <tbody {...api.getTableBodyProps({ view: "day" })}>
                  {api.weeks.map((week, i) => (
                    <tr key={i} {...api.getTableRowProps({ view: "day" })}>
                      {week.map((value, i) => (
                        <td key={i} {...api.getDayTableCellProps({ value })}>
                          <div {...api.getDayTableCellTriggerProps({ value })}>
                            {value.day}
                          </div>
                        </td>
                      ))}
                    </tr>
                  ))}
                </tbody>
              </table>
            </div>

            {/*  Month View  */}
            <div hidden={api.view !== "month"}>
              <div {...api.getViewControlProps({ view: "month" })}>
                <button {...api.getPrevTriggerProps({ view: "month" })}>
                  Prev
                </button>
                <button {...api.getViewTriggerProps({ view: "month" })}>
                  {api.visibleRange.start.year}
                </button>
                <button {...api.getNextTriggerProps({ view: "month" })}>
                  Next
                </button>
              </div>

              <table {...api.getTableProps({ view: "month", columns: 4 })}>
                <tbody {...api.getTableBodyProps({ view: "month" })}>
                  {api
                    .getMonthsGrid({ columns: 4, format: "short" })
                    .map((months, row) => (
                      <tr key={row} {...api.getTableRowProps()}>
                        {months.map((month, index) => (
                          <td
                            key={index}
                            {...api.getMonthTableCellProps({
                              ...month,
                              columns: 4,
                            })}
                          >
                            <div
                              {...api.getMonthTableCellTriggerProps({
                                ...month,
                                columns: 4,
                              })}
                            >
                              {month.label}
                            </div>
                          </td>
                        ))}
                      </tr>
                    ))}
                </tbody>
              </table>
            </div>

            {/*  Year View  */}
            <div hidden={api.view !== "year"}>
              <div {...api.getViewControlProps({ view: "year" })}>
                <button {...api.getPrevTriggerProps({ view: "year" })}>
                  Prev
                </button>
                <span>
                  {api.getDecade().start} - {api.getDecade().end}
                </span>
                <button {...api.getNextTriggerProps({ view: "year" })}>
                  Next
                </button>
              </div>

              <table {...api.getTableProps({ view: "year", columns: 4 })}>
                <tbody {...api.getTableBodyProps()}>
                  {api.getYearsGrid({ columns: 4 }).map((years, row) => (
                    <tr key={row} {...api.getTableRowProps({ view: "year" })}>
                      {years.map((year, index) => (
                        <td
                          key={index}
                          {...api.getYearTableCellProps({
                            ...year,
                            columns: 4,
                          })}
                        >
                          <div
                            {...api.getYearTableCellTriggerProps({
                              ...year,
                              columns: 4,
                            })}
                          >
                            {year.label}
                          </div>
                        </td>
                      ))}
                    </tr>
                  ))}
                </tbody>
              </table>
            </div>
          </div>
        </div>
      </Portal>
    </>
  )
}

import * as datepicker from "@zag-js/date-picker"
import { useMachine, normalizeProps } from "@zag-js/solid"
import { createMemo, createUniqueId, Portal } from "solid-js"

function DatePicker() {
  const service = useMachine(datepicker.machine, { id: createUniqueId() })

  const api = createMemo(() => datepicker.connect(service, normalizeProps))

  return (
    <>
      <div {...api().getControlProps()}>
        <input {...api().getInputProps()} />
        <button {...api().getTriggerProps()}>🗓</button>
      </div>

      <Portal>
        <div {...api().getPositionerProps()}>
          <div {...api().getContentProps()}>
            {/*  Day View  */}
            <div hidden={api().view !== "day"}>
              <div {...api().getViewControlProps()}>
                <button {...api().getPrevTriggerProps()}>Prev</button>
                <button {...api().getViewTriggerProps()}>
                  {api().visibleRangeText.start}
                </button>
                <button {...api().getNextTriggerProps()}>Next</button>
              </div>

              <table {...api().getTableProps()}>
                <thead {...api().getTableHeaderProps()}>
                  <tr {...api().getTableBodyProps()}>
                    <Index each={api().weekDays}>
                      {(day) => (
                        <th scope="col" aria-label={day().long}>
                          {day().narrow}
                        </th>
                      )}
                    </Index>
                  </tr>
                </thead>
                <tbody {...api().getTableBodyProps()}>
                  <Index each={api().weeks}>
                    {(week) => (
                      <tr {...api().getTableRowProps()}>
                        <Index each={week()}>
                          {(value) => (
                            <td
                              {...api().getDayTableCellProps({
                                value: value(),
                              })}
                            >
                              <div
                                {...api().getDayTableCellTriggerProps({
                                  value: value(),
                                })}
                              >
                                {value().day}
                              </div>
                            </td>
                          )}
                        </Index>
                      </tr>
                    )}
                  </Index>
                </tbody>
              </table>
            </div>

            {/*  Month View  */}
            <div hidden={api().view !== "month"}>
              <div {...api().getViewControlProps({ view: "month" })}>
                <button {...api().getPrevTriggerProps({ view: "month" })}>
                  Prev
                </button>
                <button {...api().getViewTriggerProps({ view: "month" })}>
                  {api().visibleRange.start.year}
                </button>
                <button {...api().getNextTriggerProps({ view: "month" })}>
                  Next
                </button>
              </div>

              <table {...api().getTableProps({ view: "month", columns: 4 })}>
                <tbody>
                  <Index
                    each={api().getMonthsGrid({ columns: 4, format: "short" })}
                  >
                    {(months) => (
                      <tr {...api().getTableBodyProps({ view: "month" })}>
                        <Index each={months()}>
                          {(month) => (
                            <td {...api().getMonthTableCellProps(month())}>
                              <div
                                {...api().getMonthTableCellTriggerProps(
                                  month(),
                                )}
                              >
                                {month().label}
                              </div>
                            </td>
                          )}
                        </Index>
                      </tr>
                    )}
                  </Index>
                </tbody>
              </table>
            </div>

            {/*  Year View  */}
            <div hidden={api().view !== "year"}>
              <div {...api().getViewControlProps({ view: "year" })}>
                <button {...api().getPrevTriggerProps({ view: "year" })}>
                  Prev
                </button>
                <span>
                  {api().getDecade().start} - {api().getDecade().end}
                </span>
                <button {...api().getNextTriggerProps({ view: "year" })}>
                  Next
                </button>
              </div>

              <table {...api().getTableProps({ view: "year", columns: 4 })}>
                <tbody>
                  <Index each={api().getYearsGrid({ columns: 4 })}>
                    {(years) => (
                      <tr {...api().getTableBodyProps({ view: "year" })}>
                        <Index each={years()}>
                          {(year) => (
                            <td
                              {...api().getYearTableCellProps({
                                ...year(),
                                columns: 4,
                              })}
                            >
                              <div
                                {...api().getYearTableCellTriggerProps({
                                  ...year(),
                                  columns: 4,
                                })}
                              >
                                {year().label}
                              </div>
                            </td>
                          )}
                        </Index>
                      </tr>
                    )}
                  </Index>
                </tbody>
              </table>
            </div>
          </div>
        </div>
      </Portal>
    </>
  )
}

<script setup lang="ts">
  import * as datepicker from "@zag-js/date-picker"
  import { normalizeProps, useMachine } from "@zag-js/vue"
  import { computed, Fragment, Teleport } from "vue"

  const service = useMachine(datepicker.machine, {
    id: "1",
  })
  const api = computed(() => datepicker.connect(service, normalizeProps))
</script>

<template>
  <>
    <div v-bind="api.getControlProps()">
      <input v-bind="api.getInputProps()" />
      <button v-bind="api.getTriggerProps()">🗓</button>
    </div>
    <Teleport to="body">
      <div v-bind="api.getPositionerProps()">
        <div v-bind="api.getContentProps()">
          <!-- Day View -->
          <div v-show="api.view !== 'day'">
            <div v-bind="api.getViewControlProps({ view: 'year' })">
              <button v-bind="api.getPrevTriggerProps()">Prev</button>
              <button v-bind="api.getViewTriggerProps()">
                {{api.visibleRangeText.start}}
              </button>
              <button v-bind="api.getNextTriggerProps()">Next</button>
            </div>

            <table v-bind="api.getTableProps({ view: 'day' })">
              <thead v-bind="api.getTableHeaderProps({ view: 'day' })">
                <tr v-bind="api.getTableRowProps({ view: 'day' })">
                  <template v-for="(day) in api.weekDays">
                    <th scope="col">
                      {{day.narrow}}
                    </th>
                  </template>
                </tr>
              </thead>
              <tbody  v-bind="api.getTableBodyProps({ view: 'day' })">
                <template v-for="(week) in api.weeks">
                  <tr v-bind="api.getTableRowProps({ view: 'day' })">
                    <template v-for="(value) in week">
                      <td v-bind="api.getDayTableCellProps({ value })">
                        <div  v-bind="api.getDayTableCellTriggerProps({ value })">
                          {{value.day}}
                        </div>
                      </td>
                    </template>
                  </tr>
                </template>
              </tbody>
            </table>
          </div>

          <!-- Month View -->
          <div v-show="api.view !== 'month'">
            <div v-bind="api.getViewControlProps({ view: 'month' })">
              <button v-bind="api.getPrevTriggerProps({ view: 'month' })">
                Prev
              </button>
              <button v-bind="api.getViewTriggerProps({ view: 'month' })">
                {{ api.visibleRange.start.year }}
              </button>
              <button v-bind="api.getNextTriggerProps({ view: 'month' })">
                Next
              </button>
            </div>

            <table v-bind="api.getTableProps({ view: 'month', columns: 4 })">
              <tbody v-bind="api.getTableBodyProps({ view: 'month' })">
                <template v-for="(months) in api.getMonthsGrid({ columns: 4, format: 'short' })">
                  <tr v-bind="api.getTableRowProps()">
                    <template v-for="(month) in months">
                      <td v-bind="api.getMonthTableCellProps({
                        ...month,
                        columns: 4,
                      })">
                        <div v-bind="api.getMonthTableCellTriggerProps({
                          ...month,
                          columns: 4,
                        })">
                          {{ month.label }}
                        </div>
                      </td>
                    </template>
                  </tr>
                </template>
              </tbody>
            </table>
          </div>

          <!-- Year View -->
          <div v-show="api.view !== 'year'">
            <div v-bind="api.getViewControlProps({ view: 'year' })">
              <button v-bind="api.getPrevTriggerProps({ view: 'year' })">
                Prev
              </button>
              <span>
                {{ api.getDecade().start }} - {{ api.getDecade().end }}
              </span>
              <button v-bind="api.getNextTriggerProps({ view: 'year' })">
                Next
              </button>
            </div>

            <table v-bind="api.getTableProps({ view: 'year', columns: 4 })">
              <tbody v-bind="api.getTableBodyProps()">
                <template v-for="(years) in api.getYearsGrid({ columns: 4 })">
                  <tr v-bind="api.getTableRowProps({ view: 'year' })">
                    <template v-for="(year) in years">
                      <td v-bind="api.getYearTableCellProps({
                        ...year,
                        columns: 4,
                      })">
                        <div v-bind="api.getYearTableCellTriggerProps({
                          ...year,
                          columns: 4,
                        })">
                          {{ year.label }}
                        </div>
                      </td>
                    </template>
                  </tr>
                </template>
              </tbody>
            </table>
          </div>
        </div>
      </div>
    </Teleport>
  </>
</template>

<script lang="ts">
  import * as datepicker from "@zag-js/date-picker"
  import { portal, useMachine, normalizeProps } from "@zag-js/svelte"

  const id = $props.id()
  const service = useMachine(datepicker.machine, ({ id }))
  const api = $derived(datepicker.connect(service, normalizeProps))
</script>

<div {...api.getControlProps()}>
  <input {...api.getInputProps()} />
  <button {...api.getTriggerProps()}>🗓</button>
</div>

<div use:portal {...api.getPositionerProps()}>
  <div {...api.getContentProps()}>
    <!-- Day View -->
    <div hidden={api.view !== "day"}>
      <div {...api.getViewControlProps({ view: "year" })}>
        <button {...api.getPrevTriggerProps()}>Prev</button>
        <button {...api.getViewTriggerProps()}>
          {api.visibleRangeText.start}
        </button>
        <button {...api.getNextTriggerProps()}>Next</button>
      </div>

      <table {...api.getTableProps({ view: "day" })}>
        <thead {...api.getTableHeaderProps({ view: "day" })}>
          <tr {...api.getTableRowProps({ view: "day" })}>
            {#each api.weekDays as day, i (i)}
              <th scope="col" aria-label={day.long}>{day.narrow}</th>
            {/each}
          </tr>
        </thead>
        <tbody {...api.getTableBodyProps({ view: "day" })}>
          {#each api.weeks as week, i (i)}
            <tr {...api.getTableRowProps({ view: "day" })}>
              {#each week as value, i (i)}
                <td {...api.getDayTableCellProps({ value })}>
                  <div {...api.getDayTableCellTriggerProps({ value })}>{value.day}</div>
                </td>
              {/each}
            </tr>
          {/each}
        </tbody>
      </table>
    </div>

    <!-- Month View -->
    <div hidden={api.view !== "month"}>
      <div {...api.getViewControlProps({ view: "month" })}>
        <button {...api.getPrevTriggerProps({ view: "month" })}> Prev </button>
        <button {...api.getViewTriggerProps({ view: "month" })}>
          {api.visibleRange.start.year}
        </button>
        <button {...api.getNextTriggerProps({ view: "month" })}> Next </button>
      </div>

      <table {...api.getTableProps({ view: "month", columns: 4 })}>
        <tbody {...api.getTableBodyProps({ view: "month" })}>
          {#each api.getMonthsGrid({ columns: 4, format: "short" }) as months, row (row)}
            <tr {...api.getTableRowProps()}>
              {#each months as month, index (index)}
                <td {...api.getMonthTableCellProps({ ...month, columns: 4 })}>
                  <div {...api.getMonthTableCellTriggerProps({ ...month, columns: 4 })}>{month.label}</div>
                </td>
              {/each}
            </tr>
          {/each}
        </tbody>
      </table>
    </div>

    <!-- Year View -->
    <div hidden={api.view !== "year"}>
      <div {...api.getViewControlProps({ view: "year" })}>
        <button {...api.getPrevTriggerProps({ view: "year" })}> Prev </button>
        <span>
          {api.getDecade().start} - {api.getDecade().end}
        </span>
        <button {...api.getNextTriggerProps({ view: "year" })}> Next </button>
      </div>

      <table {...api.getTableProps({ view: "year", columns: 4 })}>
        <tbody {...api.getTableBodyProps()}>
          {#each api.getYearsGrid({ columns: 4 }) as years, row (row)}
            <tr {...api.getTableRowProps({ view: "year" })}>
              {#each years as year, index (index)}
                <td {...api.getYearTableCellProps({ ...year, columns: 4 })}>
                  <div {...api.getYearTableCellTriggerProps({ ...year, columns: 4 })}>{year.label}</div>
                </td>
              {/each}
            </tr>
          {/each}
        </tbody>
      </table>
    </div>
  </div>
</div>

Setting the initial date

To set the initial value that is rendered by the date picker, set the value property in the machine context.

const service = useMachine(datepicker.machine, {
  defaultValue: [datepicker.parse("2022-01-01")],
})

Controlling the selected date

Use the value and onValueChange properties to programmatically control the selected date.

const service = useMachine(datepicker.machine, {
  value: [datepicker.parse("2022-01-01")],
  onValueChange(details) {
    // details => { value: DateValue[], valueAsString: string[], view: string }
    console.log("selected date:", details.valueAsString)
  },
})

Alternatively, you can also use the api.setValue method to control the selected date.

// parse the date string into a date object
const nextValue = datepicker.parse("2022-01-01")

// set the new value
api.setValue(nextValue)

Controlling the open state

Use the open and onOpenChange callbacks to programmatically control the open state of the date picker.

const service = useMachine(datepicker.machine, {
  open: true,
  onOpenChange(open) {
    console.log("open state changed to:", open)
  },
})

Alternatively, you can also use the api.setOpen method to manage the open state of the datepicker's dialog.

// open the date picker
api.setOpen(true)

// close the date picker
api.setOpen(false)

Setting the min and max dates

To constrain the date range that can be selected by the user, set the min and max properties in the machine context.

const service = useMachine(datepicker.machine, {
  min: datepicker.parse("2022-01-01"),
  max: datepicker.parse("2022-12-31"),
})

When the min or max date value is reached, the next and prev triggers will be disabled.

Changing the start of the week

Set the startOfWeek property in the machine context to change the start of the week. The property accepts a number from 0 to 6, where 0 is Sunday and 6 is Saturday.

const service = useMachine(datepicker.machine, {
  startOfWeek: 1, // Monday
})

Disabling the date picker

To disable the date picker, set the disabled property in the machine context to true.

const service = useMachine(datepicker.machine, {
  disabled: true,
})

Rendering month and year pickers

To render the month and year pickers, use the api.getMonthSelectProps and api.getYearSelectProps prop getters.

<div>
  <select {...api.getMonthSelectProps()}>
    {api.getMonths().map((month, i) => (
      <option key={i} value={month.value}>
        {month.label}
      </option>
    ))}
  </select>

  <select {...api.getYearSelectProps()}>
    {getYearsRange({ from: 1_000, to: 4_000 }).map((year, i) => (
      <option key={i} value={year}>
        {year}
      </option>
    ))}
  </select>
</div>

Marking unavailable dates

To mark specific dates as unavailable, set the isDateUnavailable function in the machine context. This function should return true for dates that are unavailable.

const service = useMachine(datepicker.machine, {
  isDateUnavailable: (date, locale) => {
    // mark weekends as unavailable
    return date.day === 0 || date.day === 6
  },
})

You can also leverage the numerous helpers from @internationalized/date to create more complex date availability rules.

import { isWeekend } from "@internationalized/date"

const service = useMachine(datepicker.machine, {
  isDateUnavailable: (date, locale) => {
    // mark weekends as unavailable
    return isWeekend(date, locale)
  },
})

Setting the calendar starting view

The calendar view is set to day by default. To change the starting view of the calendar, set the defaultView property in the machine context to either day, month, or year.

const service = useMachine(datepicker.machine, {
  defaultView: "month",
})

Setting the read-only mode

Set the readOnly property in the machine context to true to make the date picker read-only. This means that users can't change the selected date.

const service = useMachine(datepicker.machine, {
  readOnly: true,
})

Setting the focused date

The datepicker's focused date is set to either the first selected date or today's date by default.

To change the focused date, set the defaultFocusedValue property in the machine context.

const service = useMachine(datepicker.machine, {
  defaultFocusedValue: datepicker.parse("2022-01-01"),
})

Rendering the calendar inline

To render the calendar inline, we recommended setting the inline property to true.

const service = useMachine(datepicker.machine, {
  inline: true,
})

Usage within a form

To use the date picker within a form, set the name property in the machine context. This property is used to identify the date picker in the form data.

const service = useMachine(datepicker.machine, {
  name: "date",
})

Rendering fixed number of weeks

The datepicker's calendar will render the weeks needed to display all of the days in the month. Sometimes this can result in a jump in the UI when navigating between different sized months (e.g., February vs. March).

To ensure the calendar renders the maximum number of weeks (6), you can set the fixedWeeks prop to true.

const service = useMachine(datepicker.machine, {
  fixedWeeks: true,
})

Listening to date changes

To listen to date changes, use the onValueChange callback in the machine context.

const service = useMachine(datepicker.machine, {
  onValueChange(details) {
    // details => { value: DateValue[], valueAsString: string[], view: string }
    console.log("selected date:", details.valueAsString)
  },
})

Listening to view changes

When the calendar view changes by click on the view controls, the onViewChange callback is invoked.

const service = useMachine(datepicker.machine, {
  onViewChange(details) {
    // details => { view: string }
    console.log("view changed to:", details.view)
  },
})

Rendering multiple months

To display multiple months in the calendar

set the numOfMonths prop to the desired number of months
generate the weeks for the offset months using api.getOffset({ months: 1 })

const service = useMachine(datepicker.machine, {
  // ...
  numOfMonths: 2,
})

const offset = api.getOffset({ months: 1 })

Next, render the calendar for the offset months.

<tbody {...api.getTableBodyProps({ view: "day" })}>
  {offset.weeks.map((week, i) => (
    <tr key={i} {...api.getTableRowProps({ view: "day" })}>
      {week.map((value, i) => (
        <td
          key={i}
          {...api.getDayTableCellProps({
            value,
            visibleRange: offset.visibleRange,
          })}
        >
          <div
            {...api.getDayTableCellTriggerProps({
              value,
              visibleRange: offset.visibleRange,
            })}
          >
            {value.day}
          </div>
        </td>
      ))}
    </tr>
  ))}
</tbody>

Styling guide

Earlier, we mentioned that each date-picker part has a data-part attribute added to them to select and style them in the DOM.

[data-scope="date-picker"][data-part="root"] {
  /* styles for the root part */
}

[data-scope="date-picker"][data-part="input"] {
  /* styles for the input part */
}

[data-scope="date-picker"][data-part="trigger"] {
  /* styles for the trigger part */
}

[data-scope="date-picker"][data-part="content"] {
  /* styles for the input part */
}

Open State

[data-scope="date-picker"][data-part="trigger"] {
  &[data-state="open"] {
    /* styles for the open state */
  }

  &[data-state="closed"] {
    /* styles for the closed state */
  }
}

Cell States

[data-scope="date-picker"][data-part="table-cell-trigger"] {
  /* styles for the cell */

  &[data-selected] {
    /* styles for the selected date */
  }

  &[data-focus] {
    /* styles for the focused date */
  }

  &[data-disabled] {
    /* styles for the disabled date */
  }

  &[data-unavailable] {
    /* styles for the unavailable date */
  }

  &[data-today] {
    /* styles for the today date */
  }

  &[data-weekend] {
    /* styles for the weekend date */
  }
}

Methods and Properties

Machine Context

The date picker machine exposes the following context properties:

localestringThe locale (BCP 47 language tag) to use when formatting the date.
translationsIntlTranslationsThe localized messages to use.
idsPartial<{ root: string; label: (index: number) => string; table: (id: string) => string; tableHeader: (id: string) => string; tableBody: (id: string) => string; tableRow: (id: string) => string; content: string; cellTrigger: (id: string) => string; prevTrigger: (view: DateView) => string; nextTrigger: (view: DateView) => string; viewTrigger: (view: DateView) => string; clearTrigger: string; control: string; input: (index: number) => string; trigger: string; monthSelect: string; yearSelect: string; positioner: string; }>The ids of the elements in the date picker. Useful for composition.
namestringThe `name` attribute of the input element.
timeZonestringThe time zone to use
disabledbooleanWhether the calendar is disabled.
readOnlybooleanWhether the calendar is read-only.
outsideDaySelectablebooleanWhether day outside the visible range can be selected.
minDateValueThe minimum date that can be selected.
maxDateValueThe maximum date that can be selected.
closeOnSelectbooleanWhether the calendar should close after the date selection is complete. This is ignored when the selection mode is `multiple`.
valueDateValue[]The controlled selected date(s).
defaultValueDateValue[]The initial selected date(s) when rendered. Use when you don't need to control the selected date(s) of the date picker.
focusedValueDateValueThe controlled focused date.
defaultFocusedValueDateValueThe initial focused date when rendered. Use when you don't need to control the focused date of the date picker.
numOfMonthsnumberThe number of months to display.
startOfWeeknumberThe first day of the week. `0` - Sunday `1` - Monday `2` - Tuesday `3` - Wednesday `4` - Thursday `5` - Friday `6` - Saturday
fixedWeeksbooleanWhether the calendar should have a fixed number of weeks. This renders the calendar with 6 weeks instead of 5 or 6.
onValueChange(details: ValueChangeDetails) => voidFunction called when the value changes.
onFocusChange(details: FocusChangeDetails) => voidFunction called when the focused date changes.
onViewChange(details: ViewChangeDetails) => voidFunction called when the view changes.
onOpenChange(details: OpenChangeDetails) => voidFunction called when the calendar opens or closes.
isDateUnavailable(date: DateValue, locale: string) => booleanReturns whether a date of the calendar is available.
selectionModeSelectionModeThe selection mode of the calendar. - `single` - only one date can be selected - `multiple` - multiple dates can be selected - `range` - a range of dates can be selected
format(date: LocaleDetails) => stringThe format of the date to display in the input.
parse(value: string, details: LocaleDetails) => DateValueFunction to parse the date from the input back to a DateValue.
placeholderstringThe placeholder text to display in the input.
viewDateViewThe view of the calendar
defaultViewDateViewThe default view of the calendar
minViewDateViewThe minimum view of the calendar
maxViewDateViewThe maximum view of the calendar
positioningPositioningOptionsThe user provided options used to position the date picker content
openbooleanThe controlled open state of the date picker
defaultOpenbooleanThe initial open state of the date picker when rendered. Use when you don't need to control the open state of the date picker.
inlinebooleanWhether to render the date picker inline
dir"ltr" | "rtl"The document's text/writing direction.
idstringThe unique identifier of the machine.
getRootNode() => ShadowRoot | Node | DocumentA root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.

Machine API

The date picker api exposes the following methods:

focusedbooleanWhether the input is focused
openbooleanWhether the date picker is open
inlinebooleanWhether the date picker is rendered inline
viewDateViewThe current view of the date picker
getDaysInWeek(week: number, from?: DateValue) => DateValue[]Returns an array of days in the week index counted from the provided start date, or the first visible date if not given.
getOffset(duration: DateDuration) => DateValueOffsetReturns the offset of the month based on the provided number of months.
getRangePresetValue(value: DateRangePreset) => DateValue[]Returns the range of dates based on the provided date range preset.
getMonthWeeks(from?: DateValue) => DateValue[][]Returns the weeks of the month from the provided date. Represented as an array of arrays of dates.
isUnavailable(date: DateValue) => booleanReturns whether the provided date is available (or can be selected)
weeksDateValue[][]The weeks of the month. Represented as an array of arrays of dates.
weekDaysWeekDay[]The days of the week. Represented as an array of strings.
visibleRangeVisibleRangeThe visible range of dates.
visibleRangeTextVisibleRangeTextThe human readable text for the visible range of dates.
valueDateValue[]The selected date.
valueAsDateDate[]The selected date as a Date object.
valueAsStringstring[]The selected date as a string.
focusedValueDateValueThe focused date.
focusedValueAsDateDateThe focused date as a Date object.
focusedValueAsStringstringThe focused date as a string.
selectTodayVoidFunctionSets the selected date to today.
setValue(values: DateValue[]) => voidSets the selected date to the given date.
setFocusedValue(value: DateValue) => voidSets the focused date to the given date.
clearValueVoidFunctionClears the selected date(s).
setOpen(open: boolean) => voidFunction to open or close the calendar.
focusMonth(month: number) => voidFunction to set the selected month.
focusYear(year: number) => voidFunction to set the selected year.
getYears() => Cell[]Returns the months of the year
getYearsGrid(props?: YearGridProps) => YearGridValueReturns the years of the decade based on the columns. Represented as an array of arrays of years.
getDecade() => Range<number>Returns the start and end years of the decade.
getMonths(props?: MonthFormatOptions) => Cell[]Returns the months of the year
getMonthsGrid(props?: MonthGridProps) => MonthGridValueReturns the months of the year based on the columns. Represented as an array of arrays of months.
format(value: DateValue, opts?: Intl.DateTimeFormatOptions) => stringFormats the given date value based on the provided options.
setView(view: DateView) => voidSets the view of the date picker.
goToNextVoidFunctionGoes to the next month/year/decade.
goToPrevVoidFunctionGoes to the previous month/year/decade.
getDayTableCellState(props: DayTableCellProps) => DayTableCellStateReturns the state details for a given cell.
getMonthTableCellState(props: TableCellProps) => TableCellStateReturns the state details for a given month cell.
getYearTableCellState(props: TableCellProps) => TableCellStateReturns the state details for a given year cell.

Data Attributes

Root

data-scope

date-picker

data-part

root

data-state

"open" | "closed"

data-disabled

Present when disabled

data-readonly

Present when read-only

Label

data-scope

date-picker

data-part

label

data-state

"open" | "closed"

data-index

The index of the item

data-disabled

Present when disabled

data-readonly

Present when read-only

Control

data-scope

date-picker

data-part

control

data-disabled

Present when disabled

Content

data-scope

date-picker

data-part

content

data-state

"open" | "closed"

data-nested

popover

data-has-nested

popover

data-placement

The placement of the content

data-inline

Present when the content is inline

Table

data-scope

date-picker

data-part

table

data-view

The view of the table

TableHead

data-scope

date-picker

data-part

table-head

data-view

The view of the tablehead

data-disabled

Present when disabled

TableHeader

data-scope

date-picker

data-part

table-header

data-view

The view of the tableheader

data-disabled

Present when disabled

TableBody

data-scope

date-picker

data-part

table-body

data-view

The view of the tablebody

data-disabled

Present when disabled

TableRow

data-scope

date-picker

data-part

table-row

data-disabled

Present when disabled

data-view

The view of the tablerow

DayTableCell

data-scope

date-picker

data-part

day-table-cell

data-value

The value of the item

DayTableCellTrigger

data-scope

date-picker

data-part

day-table-cell-trigger

data-disabled

Present when disabled

data-selected

Present when selected

data-value

The value of the item

data-view

The view of the daytablecelltrigger

data-today

Present when the date represents today

data-focus

Present when focused

data-unavailable

Present when the date is unavailable based on the min and max date

data-range-start

Present when is the start of a range

data-range-end

Present when is the end of a range

data-in-range

Present when is within the range

data-outside-range

Present when is outside the range

data-weekend

Present when is a weekend day

data-in-hover-range

Present when in hovered range

data-hover-range-start

Present when is the start of the hovered range

data-hover-range-end

Present when is the end of the hovered range

MonthTableCell

data-scope

date-picker

data-part

month-table-cell

data-selected

Present when selected

data-value

The value of the item

MonthTableCellTrigger

data-scope

date-picker

data-part

month-table-cell-trigger

data-selected

Present when selected

data-disabled

Present when disabled

data-focus

Present when focused

data-in-range

Present when is within the range

data-view

The view of the monthtablecelltrigger

data-value

The value of the item

YearTableCell

data-scope

date-picker

data-part

year-table-cell

data-selected

Present when selected

data-value

The value of the item

YearTableCellTrigger

data-scope

date-picker

data-part

year-table-cell-trigger

data-selected

Present when selected

data-focus

Present when focused

data-in-range

Present when is within the range

data-disabled

Present when disabled

data-value

The value of the item

data-view

The view of the yeartablecelltrigger

NextTrigger

data-scope

date-picker

data-part

next-trigger

data-disabled

Present when disabled

PrevTrigger

data-scope

date-picker

data-part

prev-trigger

data-disabled

Present when disabled

Trigger

data-scope

date-picker

data-part

trigger

data-placement

The placement of the trigger

data-state

"open" | "closed"

View

data-scope

date-picker

data-part

view

data-view

The view of the view

ViewTrigger

data-scope

date-picker

data-part

view-trigger

data-view

The view of the viewtrigger

ViewControl

data-scope

date-picker

data-part

view-control

data-view

The view of the viewcontrol

Input

data-scope

date-picker

data-part

input

data-index

The index of the item

data-state

"open" | "closed"

CSS Variables

Arrow

--arrow-size

The size of the arrow

--arrow-size-half

Half the size of the arrow

--arrow-background

Use this variable to style the arrow background

--arrow-offset

The offset position of the arrow

Positioner

--transform-origin

The transform origin for animations

--reference-width

The width of the reference element

--available-width

The available width in viewport

--available-height

The available height in viewport

--x

The x position for transform

--y

The y position for transform

--z-index

The z-index value

--reference-height

The height of the root

Content

--layer-index

The index of the dismissable in the layer stack

--nested-layer-count

The number of nested date-pickers

Backdrop

--layer-index

The index of the dismissable in the layer stack

Edit this page on GitHub

2020	2021	2022	2023
2024	2025	2026	2027
2028	2029	2030	2031

S	M	T	W	T	F	S
28	29	30	1	2	3	4
5	6	7	8	9	10	11
12	13	14	15	16	17	18
19	20	21	22	23	24	25
26	27	28	29	30	31	1

S	M	T	W	T	F	S
28	29	30	1	2	3	4
5	6	7	8	9	10	11
12	13	14	15	16	17	18
19	20	21	22	23	24	25
26	27	28	29	30	31	1

Date Picker

Installation

Anatomy

Usage

Setting the initial date

Controlling the selected date

Controlling the open state

Setting the min and max dates

Changing the start of the week

Disabling the date picker

Rendering month and year pickers

Marking unavailable dates

Setting the calendar starting view

Setting the read-only mode

Setting the focused date

Rendering the calendar inline

Usage within a form

Rendering fixed number of weeks

Listening to date changes

Listening to view changes

Rendering multiple months

Styling guide

Open State

Cell States

Methods and Properties

Machine Context

Machine API

Data Attributes

CSS Variables

On this page

S	M	T	W	T	F	S
28	29	30	1	2	3	4
5	6	7	8	9	10	11
12	13	14	15	16	17	18
19	20	21	22	23	24	25
26	27	28	29	30	31	1