# DatePicker

Shows the selected date and opens a calendar in a popup.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/DatePicker.tsx)

## Overview

A date picker is a button that shows the selected date and opens a calendar in a popup. It has no text entry.

## Examples

### Basic

```tsx
import { DatePicker } from '@tempoxyz/ds'

export function Demo() {
  return (
    <DatePicker.Root>
      <DatePicker.Trigger />
      <DatePicker.Popup>
        <DatePicker.Calendar />
      </DatePicker.Popup>
    </DatePicker.Root>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/DatePicker/Basic.tsx)

### Variant

Set `variant` on `DatePicker.Trigger` to `filled` (default) or `outlined`.

```tsx
import { DatePicker, style } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.row()}>
      {(['filled', 'outlined'] as const).map((variant) => (
        <DatePicker.Root key={variant}>
          <DatePicker.Trigger variant={variant} />
          <DatePicker.Popup>
            <DatePicker.Calendar />
          </DatePicker.Popup>
        </DatePicker.Root>
      ))}
    </div>
  )
}

namespace styles {
  export const row = style({
    alignItems: 'flex-start',
    display: 'flex',
    flexWrap: 'wrap',
    gap: '24',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/DatePicker/Variant.tsx)

### Mode

Set `mode="range"` on `DatePicker.Root` to select a range. It defaults to `single`.

```tsx
import { DatePicker } from '@tempoxyz/ds'

export function Demo() {
  return (
    <DatePicker.Root mode="range">
      <DatePicker.Trigger placeholder="Select range" />
      <DatePicker.Popup>
        <DatePicker.Calendar />
      </DatePicker.Popup>
    </DatePicker.Root>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/DatePicker/Mode.tsx)

### Invalid

Set `aria-invalid` on `DatePicker.Trigger` to mark it invalid.

```tsx
import { DatePicker } from '@tempoxyz/ds'

export function Demo() {
  return (
    <DatePicker.Root>
      <DatePicker.Trigger aria-invalid />
      <DatePicker.Popup>
        <DatePicker.Calendar />
      </DatePicker.Popup>
    </DatePicker.Root>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/DatePicker/Invalid.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { DatePicker } from '@tempoxyz/ds'

<DatePicker.Root>
  <DatePicker.Trigger />
  <DatePicker.Popup>
    <DatePicker.Calendar />
  </DatePicker.Popup>
</DatePicker.Root>
```

## Guidelines

### When to Use

* Enter a date as one field in a form, such as the expiry date of an API key.
* Enter a range with `mode="range"`, such as the period of a statement export.

### When Not to Use

* Use [Calendar](/docs/components/calendar) when the grid stays visible, such as in a filter panel.
* Use [TextInput](/docs/components/text-input) for memorable dates far from today, such as a date of birth.
* Use [ChoiceGroup](/docs/components/choice-group) or [Select](/docs/components/select) for preset periods, such as 7D or Last 30 days.

### Label the Trigger

The trigger shows only the date or the placeholder, and `Field.Label` doesn't link to it. Point its `aria-labelledby` at a visible label and at the trigger's own `id`.

**Do:** Put a visible label above the trigger and reference it with `aria-labelledby`.

```tsx
/**
 * Do example for "Label the Trigger" on the DatePicker page.
 * Put a visible label above the trigger and reference it with `aria-labelledby`.
 * @module
 */
import { DatePicker, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.field()}>
      <span id="guideline-expiry-label" {...styles.label()}>
        Key expires on
      </span>
      <DatePicker.Root defaultValue={new Date(2027, 0, 31)}>
        <DatePicker.Trigger
          aria-labelledby="guideline-expiry-label guideline-expiry"
          id="guideline-expiry"
        />
        <DatePicker.Popup>
          <DatePicker.Calendar />
        </DatePicker.Popup>
      </DatePicker.Root>
    </div>
  )
}

namespace styles {
  export const field = style({ display: 'grid', rowGap: '8', width: '100% !custom' })

  export const label = style({ color: 'content.primary', typography: 'body.b3Strong' })
}
```

**Don't:** Leave the trigger to explain itself with Select date.

```tsx
/**
 * Don't example for "Label the Trigger" on the DatePicker page.
 * Don't leave the trigger to explain itself with Select date.
 * @module
 */
import { DatePicker, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.field()}>
      <DatePicker.Root>
        <DatePicker.Trigger />
        <DatePicker.Popup>
          <DatePicker.Calendar />
        </DatePicker.Popup>
      </DatePicker.Root>
    </div>
  )
}

namespace styles {
  export const field = style({ display: 'grid', width: '100% !custom' })
}
```

### State Date Limits in Text

Pass `min`, `max`, and `isDateDisabled` to `DatePicker.Root`, which passes them to `DatePicker.Calendar`. Describe the limit below the trigger, and point `aria-describedby` at it.

**Do:** State the allowed range below the trigger, such as Choose a date within one year.

```tsx
/**
 * Do example for "State Date Limits in Text" on the DatePicker page.
 * State the allowed range below the trigger, such as Choose a date within one year.
 * @module
 */
import { DatePicker, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.field()}>
      <span id="guideline-stated-limit-label" {...styles.label()}>
        Key expires on
      </span>
      <DatePicker.Root max={new Date(2027, 9, 21)} min={new Date(2026, 9, 21)}>
        <DatePicker.Trigger
          aria-labelledby="guideline-stated-limit-label guideline-stated-limit"
          aria-describedby="guideline-stated-limit-hint"
          id="guideline-stated-limit"
        />
        <DatePicker.Popup>
          <DatePicker.Calendar />
        </DatePicker.Popup>
      </DatePicker.Root>
      <span id="guideline-stated-limit-hint" {...styles.hint()}>
        Choose a date within one year.
      </span>
    </div>
  )
}

namespace styles {
  export const field = style({ display: 'grid', rowGap: '8', width: '100% !custom' })

  export const label = style({ color: 'content.primary', typography: 'body.b3Strong' })

  export const hint = style({ color: 'content.secondary', typography: 'body.b3' })
}
```

**Don't:** Leave people to find the limit by paging through the calendar.

```tsx
/**
 * Don't example for "State Date Limits in Text" on the DatePicker page.
 * Don't leave people to find the limit by paging through the calendar.
 * @module
 */
import { DatePicker, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.field()}>
      <span id="guideline-unstated-limit-label" {...styles.label()}>
        Key expires on
      </span>
      <DatePicker.Root max={new Date(2027, 9, 21)} min={new Date(2026, 9, 21)}>
        <DatePicker.Trigger
          aria-labelledby="guideline-unstated-limit-label guideline-unstated-limit"
          id="guideline-unstated-limit"
        />
        <DatePicker.Popup>
          <DatePicker.Calendar />
        </DatePicker.Popup>
      </DatePicker.Root>
    </div>
  )
}

namespace styles {
  export const field = style({ display: 'grid', rowGap: '8', width: '100% !custom' })

  export const label = style({ color: 'content.primary', typography: 'body.b3Strong' })
}
```

### Show Errors in Text

Set `aria-invalid` on `DatePicker.Trigger` to fill it red. Put the error text below the trigger and point `aria-describedby` at it. `Field.Error` doesn't link to the trigger.

**Do:** Pair the red fill with error text that names the fix.

```tsx
/**
 * Do example for "Show Errors in Text" on the DatePicker page.
 * Pair the red fill with error text that names the fix.
 * @module
 */
import { DatePicker, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.field()}>
      <span id="guideline-error-text-label" {...styles.label()}>
        Key expires on
      </span>
      <DatePicker.Root defaultValue={new Date(2026, 9, 1)}>
        <DatePicker.Trigger
          aria-labelledby="guideline-error-text-label guideline-error-text"
          aria-describedby="guideline-error-text-error"
          aria-invalid
          id="guideline-error-text"
        />
        <DatePicker.Popup>
          <DatePicker.Calendar />
        </DatePicker.Popup>
      </DatePicker.Root>
      <span id="guideline-error-text-error" {...styles.error()}>
        Choose a date after today.
      </span>
    </div>
  )
}

namespace styles {
  export const field = style({ display: 'grid', rowGap: '8', width: '100% !custom' })

  export const label = style({ color: 'content.primary', typography: 'body.b3Strong' })

  export const error = style({ color: 'content.negative', typography: 'body.b3' })
}
```

**Don't:** Mark the trigger invalid without saying what is wrong.

```tsx
/**
 * Don't example for "Show Errors in Text" on the DatePicker page.
 * Don't mark the trigger invalid without saying what is wrong.
 * @module
 */
import { DatePicker, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.field()}>
      <span id="guideline-error-ring-label" {...styles.label()}>
        Key expires on
      </span>
      <DatePicker.Root defaultValue={new Date(2026, 9, 1)}>
        <DatePicker.Trigger
          aria-labelledby="guideline-error-ring-label guideline-error-ring"
          aria-invalid
          id="guideline-error-ring"
        />
        <DatePicker.Popup>
          <DatePicker.Calendar />
        </DatePicker.Popup>
      </DatePicker.Root>
    </div>
  )
}

namespace styles {
  export const field = style({ display: 'grid', rowGap: '8', width: '100% !custom' })

  export const label = style({ color: 'content.primary', typography: 'body.b3Strong' })
}
```

### Match the Fields Around It

`DatePicker.Trigger` is as tall as a [TextInput](/docs/components/text-input), at 48px. Use the same variant as the fields beside it.

**Do:** Give the trigger the variant of the inputs in the same row.

```tsx
/**
 * Do example for "Match the Fields Around It" on the DatePicker page.
 * Give the trigger the variant of the inputs in the same row.
 * @module
 */
import { DatePicker, style, TextInput } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <TextInput.Group {...styles.cell()}>
        <TextInput.Control aria-label="Key name" defaultValue="Checkout server" />
      </TextInput.Group>
      <DatePicker.Root defaultValue={new Date(2027, 0, 31)}>
        <DatePicker.Trigger aria-label="Key expires on" {...styles.cell()} />
        <DatePicker.Popup>
          <DatePicker.Calendar />
        </DatePicker.Popup>
      </DatePicker.Root>
    </div>
  )
}

namespace styles {
  export const cell = style({ flex: '1 !custom', minWidth: '0 !custom' })

  export const row = style({
    alignItems: 'center',
    display: 'flex',
    gap: '8',
    width: '100% !custom',
  })
}
```

**Don't:** Mix an `outlined` trigger with filled inputs.

```tsx
/**
 * Don't example for "Match the Fields Around It" on the DatePicker page.
 * Don't mix an `outlined` trigger with filled inputs.
 * @module
 */
import { DatePicker, style, TextInput } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <TextInput.Group {...styles.cell()}>
        <TextInput.Control aria-label="Key name" defaultValue="Checkout server" />
      </TextInput.Group>
      <DatePicker.Root defaultValue={new Date(2027, 0, 31)}>
        <DatePicker.Trigger aria-label="Key expires on" variant="outlined" {...styles.cell()} />
        <DatePicker.Popup>
          <DatePicker.Calendar />
        </DatePicker.Popup>
      </DatePicker.Root>
    </div>
  )
}

namespace styles {
  export const cell = style({ flex: '1 !custom', minWidth: '0 !custom' })

  export const row = style({
    alignItems: 'center',
    display: 'flex',
    gap: '8',
    width: '100% !custom',
  })
}
```

## Content

* **Label:** Name the date, such as Key expires on or Start date.
* **Placeholder:** Keep Select date in single mode. In range mode, use Select dates.
* **Value:** The trigger formats it with `Intl.DateTimeFormat` in the medium date style for `locale`, such as Jan 31, 2027, and a range as one span.

## Accessibility

A date picker renders a button that opens a calendar in a popup dialog. It follows the [WAI-ARIA Authoring Practices date picker dialog example](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/), except that the popup is not modal.

### Semantics

* **DatePicker.Trigger (button):** Announces that it opens a dialog, and whether the dialog is open.
* **DatePicker.Popup (dialog):** Renders a `dialog` named "Choose date" unless you pass `aria-label`.
* **DatePicker.Calendar (grid):** Uses the grid semantics described on [Calendar](/docs/components/calendar#accessibility).
* **Target Size (48px):** The trigger is above the 24px WCAG 2.2 minimum.

### Keyboard

* **Move Focus to the Trigger (Tab):** Moves focus to the trigger.
* **Open the Popup (Enter or Space):** On the trigger, opens the popup and focuses a day.
* **Move Through Dates (Arrow keys):** Home, End, Page Up, and Page Down also move, as on [Calendar](/docs/components/calendar#keyboard).
* **Select a Day (Enter or Space):** On a day, selects it and closes the popup. In `range` mode, the popup closes after the end date.
* **Move Within the Popup (Tab and Shift+Tab):** Move between the month buttons and the day grid.
* **Close the Popup (Escape):** Closes the popup without a change, and returns focus to the trigger.

### Focus

When the popup opens, focus moves to the selected day, or today. The popup doesn't trap focus, so Tab can leave it.

### Your Responsibilities

* **Name the Trigger (aria-labelledby):** Point it at the visible label and the trigger, so the name includes the date.
* **Name Each Popup (aria-label):** If a page has several pickers, name each popup, such as "Choose start date".
* **Link the Error Text (aria-describedby):** Point it at the error text below the trigger.

## Related

[Calendar](/docs/components/calendar)

Use for an inline month grid.

[TextInput](/docs/components/text-input)

Use for typed and native dates.

[Popover](/docs/components/popover)

Use for other anchored popups.

[Field](/docs/components/field)

Use for labels and errors on other controls.

[Forms](/docs/patterns/forms)

Covers placing a date among other fields.
