Calendar
Calendar selects one timezone-safe ISO date in a localizable month grid with complete keyboard navigation and explicit constraints.
Overview and decision boundary
Use Calendar to select one ISO calendar date in a custom inline month grid when native Input type=date is not sufficient.
Do not add DatePicker popup ownership, ranges, multiple selection, events, availability data, scheduling, recurrence, time, or timezone conversion to Calendar.
Installation and imports
Install the editable registry source, or use the matching package entrypoint when the product keeps Nerio as a workspace dependency.
pnpm exec nerio add calendarimport { Calendar } from "@nerio-ui/ui/client";Usage
import { Calendar } from "@nerio-ui/ui/client";<Calendar aria-label="Release date" defaultValue="2026-06-15" min="2026-06-01" max="2026-06-30" firstDayOfWeek={1}/>Variants
| Contract | Description |
|---|---|
Uncontrolled | Use defaultValue and defaultMonth for the common inline path. |
Controlled | Own value and month independently when product composition requires it. |
Localized | Set locale, firstDayOfWeek, and labels without changing ISO values. |
Anatomy
| Slot | Description |
|---|---|
root | Named Calendar group and state owner. |
header | Previous-month action, live month heading, and next-month action. |
grid | Six-week native table with ARIA grid semantics. |
weekday-header | Locale-aware weekday labels with full abbr names. |
row | One visual calendar week. |
cell | Gridcell carrying selected state. |
day | Native date button participating in roving focus. |
States
| State | Behavior |
|---|---|
Default | Shows one month with one keyboard tab stop. |
Selected | Uses accent fill and border, aria-selected on the gridcell, and a localized selected label on the focused day. |
Today | Uses aria-current=date and weight without changing selection. |
Outside month | Remains available with muted text and moves the visible month when selected. |
Unavailable | Min, max, or isDateDisabled prevents selection and adds aria-disabled. |
Read-only | Keeps navigation and focus available while preventing value changes. |
Disabled | Disables navigation and every day button. |
Motion
- State feedback uses shared hover and focus duration and easing tokens.
- Month changes are immediate; reduced motion removes nonessential transitions.
Accessibility
- Requires exactly one accessible name through aria-label or aria-labelledby.
- Uses a native table with grid semantics, full localized date labels, weekday abbreviations, and one roving day tab stop.
- Arrow keys move by day or week, Home and End move within the week, Page keys move by month, and Shift plus Page keys move by year.
- Enter and Space select the focused date; unavailable, disabled, and read-only states cannot change the value.
- Controlled and uncontrolled selected-date and visible-month state use timezone-safe YYYY-MM-DD values.
- Locale formats labels while firstDayOfWeek intentionally controls the visual week start; locale defaults to en-US for deterministic SSR.
- The heading announces visible-month changes politely; the focused day includes localized selection context; unavailable days expose aria-disabled and use the disabled foreground token without text decoration.
- DatePicker, ranges, multiple selection, events, availability, scheduling, recurrence, time, timezone conversion, fetching, and persistence remain outside Calendar.
Review the shared responsibility and evidence boundaries in the Accessibility foundation alongside this component-specific contract. Use the Spacing & layout foundation for shared density, wrapping, overflow, reflow, and component-versus-product ownership guidance. The Color foundation, Typography foundation, and Localization foundation define the shared visual-role, text-resilience, direction, and locale boundaries used by component examples.
API
| Prop | Type | Description |
|---|---|---|
value / defaultValue | CalendarDate | Controlled or uncontrolled selected YYYY-MM-DD date. |
onValueChange | (date) => void | Receives one valid, available ISO calendar date. |
month / defaultMonth | CalendarDate | Visible month; input normalizes to its first day. |
onMonthChange | (month) => void | Receives the visible month as YYYY-MM-01. |
min / max | CalendarDate | Inclusive ISO date boundaries. |
isDateDisabled | (date) => boolean | Consumer policy hook for unavailable dates. |
locale | string | string[] | Intl locale for month, weekday, and date labels; defaults to en-US for deterministic SSR. |
firstDayOfWeek | 0–6 | Explicit Sunday-through-Saturday week start; defaults to Sunday. |
today | CalendarDate | Consumer-owned current date for today styling and empty-state month selection. |
labels | CalendarLabels | Localized month-action names and selected-date context. |
disabled / readOnly | boolean | Availability and selection behavior. |
aria-label / aria-labelledby | string | Exactly one required Calendar naming strategy. |
ref | HTMLDivElement | Accesses the Calendar root group. |
Implementation contract
| Contract | Value |
|---|---|
Behavior | Native buttons in a labelled ARIA grid; no date runtime dependency. |
Entrypoint | @nerio-ui/ui/client |
Value | Timezone-independent ISO YYYY-MM-DD calendar date. |
Registry | nerio add calendar installs Calendar plus Button and source dependencies. |
Boundary | One visible month and one selected date; product workflows remain external. |
Styling contract
| Contract | Value |
|---|---|
Authoring | Complete, statically detectable Tailwind CSS v4 recipes own component visuals. |
Values | Semantic and component --n-* variables remain the canonical customization layer. |
Overrides | Customizable slots merge consumer className values with tailwindCn so conflicting utilities resolve deterministically. |
Residual CSS | Only shared keyframes and scoped no-Preflight compatibility rules remain; there is no parallel visual selector layer. |
Design notes
- Use Calendar to select one ISO calendar date in a custom inline month grid when native Input type=date is not sufficient.
Do / do not
Do
- Use native Input type=date when browser-owned picker UI is sufficient.
- Use Calendar when an inline, tokenized, localizable date grid is required.
- Supply today during SSR when the product needs a stable timezone policy.
Do not
- Add date ranges, multiple selection, presets, or natural-language parsing.
- Embed events, prices, availability data, scheduling, or recurrence.
- Use Calendar as DatePicker; popup and form composition belongs to DatePicker.
Related components
Tokens
| Group | Tokens | Controls |
|---|---|---|
Container | --n-calendar-width / padding / radius / border / background | Bounded month surface. |
Grid | --n-calendar-grid-gap / cell-gap / cell-size | Month spacing and density. |
Type | --n-calendar-heading-* / weekday-* / day-font-size | Localized hierarchy. |
Days | --n-calendar-day-* | Default, hover, outside, unavailable, and selected states. |
Today | --n-calendar-today-font-weight | Non-color current-date distinction. |
Motion | --n-calendar-duration / easing | Immediate tokenized feedback with reduced motion. |