# Calendar

A month on a plate. The month and year sit on two drums behind a window and roll when you page; the chosen day is a latched cap, a range is a groove cut between two caps, and events are lamps named in the line below.

Kit part · With the Kit · https://tactileui.dev/parts/calendar

> The code and styling for this part come with the Tactile UI Kit, which is in the Founder Pass. Sign in if you have it. Sign in: https://tactileui.dev/auth/sign-in The price: https://tactileui.dev/pricing

## Anatomy

A custom element that builds its own light DOM. Dates are whole days since 1970 in UTC, so no time zone can move one. Each drum is a strip of three faces (last, this and next) in a recess, shaded like a cylinder. The chosen day takes the contrast cap and the pressed shadow.

## Variants

- Range · a groove between two caps
- Closed weekends, nothing before today
- Locale · en-US, Sunday first

## States

- Day
- Hover
- Focus
- Today
- Event
- Chosen
- In a range
- Unavailable

## Props and options

| Name | Kind | Description |
| - | - | - |
| value | attribute | The chosen day in ISO form. A lone start while picking. |
| mode | attribute | One day, or a range picked with two presses. |
| month | attribute | The month on the plate when there is no value. Also a property: set it to page from code. |
| min · max | attribute | Days outside are struck through: focusable, never chosen. The page keys stop at them. |
| disabled-dates | attribute | Single closed days. |
| disabled-weekdays | attribute | Closed weekdays, 0 Sunday to 6 Saturday. |
| locale | attribute | Names and the week’s first day, through Intl. Falls back to the nearest lang, then the browser. |
| first-day | attribute | Override the locale’s first day of the week. |
| today | attribute | Fix “today” (tests, screenshots). Otherwise the visitor’s own date. |
| empty-note | attribute | The words under the grid for a day with no events. |
| focusDate(iso) | method | Page to that day’s month and move the tab stop there. |
| input · change | event | change when a day, or a whole range, is chosen; input when a range’s start is. |
| Arrows | keyboard | Crossing a month’s edge pages the plate. |
| Home · End | keyboard | The first and last day of the focused week. |
| PageUp · PageDown | keyboard | The same day, clamped to the month’s length. |
| Enter · Space | keyboard | Choose the focused day. |

## Usage notes

Page with the keys and watch the drums roll. In the grid: arrows move a day or a week, Page Up/Down a month (Shift for a year), Enter picks.

## Accessibility

- One day holds the tab stop; arrows move it. Room 2, Clash: two bookings”), with “today” and “unavailable” where true.
- Chosen is also the contrast cap and a heavier figure, not only a colour.
- Every lamp has its words: in the day’s name, and printed in the line under the grid for the day in focus.

## Related parts

- [Date picker](https://tactileui.dev/parts/date-picker): A date field with its calendar card in a slot underneath: type a date in any common form for your locale, or press the key and the card slides out. Single dates and ranges; shown the Intl way, posted as ISO.
- [Table](https://tactileui.dev/parts/table): Rows of data with printed column labels, figures right-aligned in columns, and status in lamps with words.
- [Lamp](https://tactileui.dev/parts/lamp): The only colour in the kit: a lamp that is on. Green is on, amber is waiting, red is recording or failing, blue is linked, white is standing by. Always next to words.