# Calendar

A month grid for picking one date or a date range.

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

## Overview

Shows one month at a time. The month buttons page through months, and each day is a button.

## Examples

### Basic

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

export function Demo() {
  return <Calendar defaultValue={new Date()} />
}
```

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

### Mode

Set `mode="range"` to select a `{ from, to }` range. The default is `single`.

```tsx
import { Calendar } from '@tempoxyz/ds'
import { useState } from 'react'

export function Demo() {
  const [range, setRange] = useState<Calendar.Range | null>(null)

  return <Calendar mode="range" onValueChange={setRange} value={range} />
}
```

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

### Disabled Dates

Set `min`, `max`, or `isDateDisabled` to mark unavailable days.

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

export function Demo() {
  const today = new Date()

  return (
    <Calendar
      isDateDisabled={(date) => date.getDay() === 0}
      max={new Date(today.getFullYear(), today.getMonth() + 1, 20)}
      min={new Date(today.getFullYear(), today.getMonth() - 1, 5)}
    />
  )
}
```

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

### Locale

Set `locale` to format the month and weekdays. The default is the browser's locale.

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

export function Demo() {
  return <Calendar locale="de-DE" />
}
```

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

## Anatomy

Import the component and assemble its parts.

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

<Calendar />
```

## Guidelines

### When to Use

* Pick a date near today with the grid always on screen, such as a start date in a side panel.
* Pick a date range with `mode="range"`, such as the period for an activity export.
* Show which days are available, such as business days for a bank withdrawal.

### When Not to Use

* If the date is one field in a form, use [DatePicker](/docs/components/date-picker). It opens the same calendar in a popup.
* Use [TextInput](/docs/components/text-input) for dates far from today, such as a date of birth.
* Use [ChoiceGroup](/docs/components/choice-group) for preset ranges, such as 24H, 7D, and 30D above a chart.

### Explain Unavailable Days

Set `min`, `max`, or `isDateDisabled`, and state the rule in text beside the calendar, not in a tooltip on each day. The month buttons can't page past `min` or `max`.

**Do:** State the rule below the calendar, such as Bank withdrawals settle on business days.

```tsx
/**
 * Do example for "Explain Unavailable Days" on the Calendar page.
 * State the rule below the calendar, such as Bank withdrawals settle on business days.
 * @module
 */
import { Calendar, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.stack()}>
      <Calendar
        defaultMonth={new Date(2026, 9, 1)}
        isDateDisabled={(date) => date.getDay() === 0 || date.getDay() === 6}
      />
      <span {...styles.note()}>Bank withdrawals settle on business days.</span>
    </div>
  )
}

namespace styles {
  export const stack = style({ display: 'flex', flexDirection: 'column', rowGap: '12' })

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

**Don't:** Disable days without saying why.

```tsx
/**
 * Don't example for "Explain Unavailable Days" on the Calendar page.
 * Don't disable days without saying why.
 * @module
 */
import { Calendar } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Calendar
      defaultMonth={new Date(2026, 9, 1)}
      isDateDisabled={(date) => date.getDay() === 0 || date.getDay() === 6}
    />
  )
}
```

### Show a Range in Text Too

In range mode, `onValueChange` runs on every press: `{ from }` after the first, `{ from, to }` after the second. Apply a filter only after `to` is set.

**Do:** Show the selected range as text, such as Oct 1 to 14, 2026.

```tsx
/**
 * Do example for "Show a Range in Text Too" on the Calendar page.
 * Show the selected range as text, such as Oct 1 to 14, 2026.
 * @module
 */
import { Calendar, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.stack()}>
      <span {...styles.range()}>Oct 1 to 14, 2026</span>
      <Calendar
        defaultValue={{ from: new Date(2026, 9, 1), to: new Date(2026, 9, 14) }}
        mode="range"
      />
    </div>
  )
}

namespace styles {
  export const stack = style({ display: 'flex', flexDirection: 'column', rowGap: '12' })

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

**Don't:** Rely on the highlighted days alone to show the range.

```tsx
/**
 * Don't example for "Show a Range in Text Too" on the Calendar page.
 * Don't rely on the highlighted days alone to show the range.
 * @module
 */
import { Calendar } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Calendar
      defaultValue={{ from: new Date(2026, 9, 1), to: new Date(2026, 9, 14) }}
      mode="range"
    />
  )
}
```

### Start on the Month of the Task

`defaultMonth` falls back to the selected day's month, then the current month. Set it to the month of the task, such as the start of a statement period. To sync the page with a typed [TextInput](/docs/components/text-input), control it with `month` and `onMonthChange`.

**Do:** Open on the month the task is about.

```tsx
/**
 * Do example for "Start on the Month of the Task" on the Calendar page.
 * Open on the month the task is about.
 * @module
 */
import { Calendar, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.stack()}>
      <span {...styles.label()}>Start of the September statement</span>
      <Calendar defaultMonth={new Date(2026, 8, 1)} />
    </div>
  )
}

namespace styles {
  export const stack = style({ display: 'flex', flexDirection: 'column', rowGap: '12' })

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

**Don't:** Open on the current month when the task is about another one.

```tsx
/**
 * Don't example for "Start on the Month of the Task" on the Calendar page.
 * Don't open on the current month when the task is about another one.
 * @module
 */
import { Calendar, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.stack()}>
      <span {...styles.label()}>Start of the September statement</span>
      <Calendar defaultMonth={new Date(2026, 9, 1)} />
    </div>
  )
}

namespace styles {
  export const stack = style({ display: 'flex', flexDirection: 'column', rowGap: '12' })

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

### Follow the Locale

`locale` defaults to the browser's locale, and `weekStartsOn` to that locale's first weekday. Leave both unset unless the product uses a fixed locale. The month button names default to English, so translate them through `labels`.

**Do:** Let the locale set the first weekday, and translate `labels`.

```tsx
/**
 * Do example for "Follow the Locale" on the Calendar page.
 * Let the locale set the first weekday, and translate `labels`.
 * @module
 */
import { Calendar } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Calendar
      defaultMonth={new Date(2026, 9, 1)}
      labels={{ next: 'Nächster Monat', previous: 'Vorheriger Monat' }}
      locale="de-DE"
    />
  )
}
```

**Don't:** Override `weekStartsOn` against the locale, such as Sunday first in German.

```tsx
/**
 * Don't example for "Follow the Locale" on the Calendar page.
 * Don't override `weekStartsOn` against the locale, such as Sunday first in German.
 * @module
 */
import { Calendar } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Calendar
      defaultMonth={new Date(2026, 9, 1)}
      labels={{ next: 'Nächster Monat', previous: 'Vorheriger Monat' }}
      locale="de-DE"
      weekStartsOn={0}
    />
  )
}
```

## Content

If a date maps to a time, such as a statement cutoff, name the time zone, such as UTC.

## Accessibility

Follows the [WAI-ARIA grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/), as in the [date picker dialog example](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/).

### Semantics

* **Month Grid (grid):** A table labelled by the month heading.
* **Weeks and Weekdays (gridcell):** Weekday names are column headers, and each week is a row of day cells.
* **Days (button):** Named with the full localized date, such as "Tuesday, October 20, 2026".
* **Today and Selection (aria-selected):** Today is marked as the current date. Selected days, including every day in a range, are marked.
* **Unavailable Days (aria-disabled):** Days outside the allowed range stay focusable and announced.
* **Month Buttons:** Named "Previous month" and "Next month". Translate them with `labels`.

### Keyboard

* **Move into the Calendar (Tab):** Moves focus to the month buttons, then to one day in the grid.
* **Next or Previous Day (Right Arrow and Left Arrow):** Moves focus to the next or previous day.
* **Next or Previous Week (Down Arrow and Up Arrow):** Moves focus to the same day in the next or previous week.
* **First or Last Day of the Week (Home and End):** Moves focus to the first or last day of the week.
* **Next or Previous Month (Page Down and Page Up):** Moves focus to the same day in the next or previous month.
* **Next or Previous Year (Shift+Page Down or Page Up):** Moves focus to the same day in the next or previous year.
* **Select the Focused Day (Enter or Space):** Selects the focused day. In `range` mode, the first press sets the start, the second the end.

### Focus

Focus starts on the selected day or today. Moving past the shown month turns the page, and focus stops at `min` and `max`.

### Announcements

Turning the page announces the new month in a polite live region.

### Your Responsibilities

* **Localize Labels (labels):** Translate the month buttons. Set `locale` to match the page language.
* **Explain Unavailable Days (isDateDisabled):** Explain the rule in nearby text, such as "Weekends are unavailable".

## Related

[DatePicker](/docs/components/date-picker)

Use for a date field in a form.

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

Use for typed dates.

[ChoiceGroup](/docs/components/choice-group)

Use for preset ranges.

[Field](/docs/components/field)

Use for labelling the date and its constraints.
