# Calendar month (goodtabs UI)

A month grid with event dots, arrow key navigation and month paging.

## Install

```bash
npx shadcn@latest add https://ui.goodtabs.co/r/calendar-month.json
```

Or, with the @goodtabs namespace configured in components.json: `npx shadcn@latest add @goodtabs/calendar-month`

## Usage

```tsx
import { CalendarMonth } from "@/components/ui/calendar-month"

<CalendarMonth defaultMonth="2026-11-01" events={events} selected={day} onSelect={setDay} />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| defaultMonth | `string` |  | ISO date. Only the year and month are used. |
| events | `{ date: string; label: string }[]` | `[]` | Days that carry a dot. |
| selected | `string` |  | Selected day as an ISO date. |
| onSelect | `(date: string) => void` |  | Called when a day is picked. |
| weekStartsOn | `0 | 1` | `1` | 0 for Sunday, 1 for Monday. |

## When to use

- Showing what is on across a month at a glance
- A schedule or release calendar with a day detail beside it

## When not to use

- Picking a date inside a form field: use a date field
- Hour by hour planning, which needs a week or day view

## Notes for agents

- Dates are ISO strings, never Date objects, so server and client agree on the day
- The grid is one tab stop. Arrows move by day and week, Home and End by week, Page Up and Down by month
- Event labels join the day button's accessible name; the dots are decorative
- It takes a function, so a demo that passes onSelect must be a client component
- Month and day names are formatted in en-US

## The maths

- Blank cells before the 1st are (weekday of the 1st - week start + 7) mod 7.
- Rows are ceil((blanks + days in month) / 7), so a month takes four to six rows.

Docs: https://ui.goodtabs.co/components/calendar-month