[](https://www.npmjs.com/package/@dateforge/react-calendar)
[](https://app.codecov.io/gh/kirilinsky/dateforge-react-calendar)
[](https://github.com/kirilinsky/dateforge-react-calendar/actions/workflows/publint.yml)
[](https://github.com/kirilinsky/dateforge-react-calendar/actions/workflows/ssr.yml)
[](https://github.com/kirilinsky/dateforge-react-calendar/actions/workflows/a11y.yml)
[](https://securityscorecards.dev/viewer/?uri=github.com/kirilinsky/dateforge-react-calendar)
[](https://badge.socket.dev/npm/package/@dateforge/react-calendar)
[](https://www.chromatic.com/library?appId=69edcfe5e2f1e060b1cce900)
[](https://codspeed.io/kirilinsky/dateforge-react-calendar?utm_source=badge)
# @dateforge/react-calendar
### [๐ Live Demo](https://calendar-demo-pi.vercel.app/) ยท [๐ Docs](https://calendar-demo-pi.vercel.app/docs) ยท [๐ Storybook](https://kirilinsky.github.io/dateforge-react-calendar/)
**A modular React calendar toolkit that starts tiny and grows with your product.**
Monolithic pickers ship the grid, the toolbar, the time picker, the presets, the layout opinions โ and all the weight. DateForge ships only what you use: every module is its own bundle on its own subpath, sharing one calendar core.
- **Zero runtime dependencies.** React 18/19 peer, nothing else.
- **SSR-safe.** No hydration mismatches โ server render tested in CI.
- **Accessible.** Keyboard-first, roving focus, axe-audited, WCAG-checked contrast in every built-in theme.
- **Themeable.** 28 light/dark theme families, 8 appearances, gradient mode, or bring your own tokens.
- **Pay per module.** A minimal calendar stays around 20 KB min+gzip; size budgets are enforced in CI.
## Install
```bash
npm i @dateforge/react-calendar
```
Styles ship with the components: with ESM (any bundler) the CSS is picked up automatically via the modules' own stylesheet imports. **CJS consumers import the stylesheet once:** `import '@dateforge/react-calendar/style.css'`.
## 10-second start
One import, zero composition:
```tsx
import { useState } from "react";
import { SimpleCalendar } from "@dateforge/react-calendar/prebuilt";
export function Example() {
const [date, setDate] = useState(null);
return ;
}
```
### Prebuilt gallery
Every prebuilt is a ready recipe over the same primitives, with plain-`Date` props (`value`, `defaultValue`, `onChange`, `locale`, `min`/`max`, `disabled`, `theme`, `appearance`, `gradient`, `scheme`):
```tsx
import {
DatePicker,
MonthPicker,
MultiMonthCalendar,
SimpleCalendar,
} from "@dateforge/react-calendar/prebuilt";
// header + day grid
// typed input + grid + Today
// year stepper + 12-month grid
// 6-month range board
```
## Compose your own
When a prebuilt stops fitting, drop one level down: `Calendar` takes a compiled `config` (from `createCalendarConfig`) and any mix of modules as children. The root is a CSS grid โ `cols` on the root declares columns, `col` on a module places it.
```tsx
import {
Calendar,
commonPresets,
createCalendarConfig,
} from "@dateforge/react-calendar";
import { CalendarDays } from "@dateforge/react-calendar/modules/days";
import { CalendarPresets } from "@dateforge/react-calendar/modules/presets";
import {
CalendarToolbar,
CalendarToolbarMonthTrigger,
CalendarToolbarNext,
CalendarToolbarPrev,
CalendarToolbarYearTrigger,
} from "@dateforge/react-calendar/modules/toolbar";
const config = createCalendarConfig({
mode: "range",
locale: "de-DE",
disabled: { weekends: true },
});
export function BookingCalendar() {
return (
console.log(range)} // { start: Date, end: Date } | null
>
);
}
```
Remove a line, remove a feature. Add a module, add a workflow. Order in JSX is visual flow โ no `order` props, no slots.
The `onChange` value shape is derived from `unit` ร `mode` alone: `day`+`single` โ `Date | null`, `day`+`multiple` โ `Date[]`, any single span (`range`, or `week`/`month` single) โ `{ start, end } | null`, any multi span โ `{ start, end }[]`.
## Modules
Import from `@dateforge/react-calendar/modules`, or per subpath (`โฆ/modules/days`, `โฆ/modules/toolbar`, โฆ) for the smallest possible bundle.
| Module | Use it for |
| --- | --- |
| `CalendarToolbar` + primitives | Composable header: prev/next (unit-aware), month/year triggers and labels, Home, Apply, clock |
| `CalendarDays` | Classic month grid โ single, multiple, range, multi-range; `offset` for multi-month boards |
| `CalendarMonthsGrid` / `CalendarYearsGrid` | Month/year picking or fast jumps |
| `CalendarDaysTrack` / `CalendarMonthsTrack` / `CalendarYearsTrack` | Physics-based scrollable strips for compact and mobile layouts |
| `CalendarTimeWheel` / `CalendarMonthsWheel` / `CalendarYearsWheel` | iOS-style drum pickers, range-bound aware (`bound="from" \| "to"`) |
| `CalendarManualInput` | Typed, segment-based date entry with keyboard stepping |
| `CalendarPresets` | Shortcuts โ `commonPresets`, `relativePresets`, or `definePreset` your own |
| `CalendarSelectedDates` | Selected-date chips with overflow and per-chip clear |
| `CalendarInfo` | Selection metrics, relative hints, empty text |
| `CalendarLunar` | Information-only lunar phase strip |
## Features
- **Selection axes** โ `mode`: `single` / `multiple` / `range` / `multi-range` ร `unit`: `day` / `week` / `month`. Plus `minSpan`/`maxSpan`, `maxDates`, `maxRanges`.
- **Disabled vs excluded** โ `disabled` days can't be picked; `exclude` days are cut out of emitted spans (business-day flows), with segments reported in change details.
- **28 theme families** โ each with light + dark: `abyss`, `aurora`, `bauhaus`, `chalk`, `crimson`, `cyber`, `dracula`, `eclipse`, `espresso`, `fjord`, `graphite`, `industrial`, `meadow`, `mint`, `monsoon`, `nebula`, `neon`, `noir`, `pearl`, `prism`, `riso`, `sandstone`, `slate`, `snow`, `solar`, `split`, `temporal`, `velvet`.
- **8 appearances** (shape/spacing, independent of color): `zenith`, `airy`, `bubble`, `compact`, `loft`, `press`, `soft`, `square`.
- **Gradient mode** โ `gradient` on the root adds corner glows and gradient selected fills, pure CSS, theme-driven.
- **Scheme control** โ `scheme="auto" | "light" | "dark"`, controllable via `onSchemeChange`; no dark-mode flash on SSR.
- **Locales via `Intl`** โ month/weekday names, digits, and week start derive from any BCP-47 `locale`; no locale files to import.
- **RTL** โ logical properties throughout; the calendar follows the inherited `dir`.
- **Time** โ `withTime`, 12/24-hour, `ampmLabels`, `defaultTime`, and a `minTime`/`maxTime` window enforced by the core.
- **Time zones & DST** โ IANA `timeZone` for "today" resolution, with explicit ambiguous/nonexistent-time policies.
- **Presets** โ built-in packs plus `definePreset` with validation context (disabled/min/max aware).
- **Accessibility** โ full keyboard navigation, focus management, live announcements, axe test suite in CI.
- **Validation hooks** โ `onValidationReject` tells you what was refused and why; `onViewChange` tracks navigation.
### Theming in one minute
```tsx
import { Calendar, createTheme } from "@dateforge/react-calendar";
import { nebula } from "@dateforge/react-calendar/themes";
import { compact } from "@dateforge/react-calendar/appearances";
// Built-in: by name (generated stylesheet) or by object (tree-shaken)
// Custom: common tokens + per-mode overrides โ a light/dark family
const brand = createTheme({
accent: "#2563eb",
range: "#22c55e",
light: { backdrop: "#f8fafc" },
dark: { backdrop: "#0f172a", text: "#f8fafc" },
});
```
## Bundle size
Budgets from [`.size-limit.json`](./.size-limit.json), min+gzip, enforced on every commit (React excluded):
| Import | Budget |
| --- | --- |
| `Calendar` only | < 18 KB |
| `Calendar` + `CalendarDays` | < 21.5 KB |
| `Calendar` + `CalendarDays` + theme + appearance | < 25.5 KB |
| `Calendar` + Toolbar + `CalendarDays` | < 26 KB |
| `SimpleCalendar` (prebuilt, one import) | < 27 KB |
Dual ESM/CJS, `sideEffects` limited to CSS, subpath exports per module โ bundlers drop everything you don't touch.
## Migrating from v2
v3 is a clean rebuild. The three headline breaking changes:
- **Config object instead of flat props.** `` became `createCalendarConfig({ mode, locale, min, โฆ })` passed as one `config` prop โ compiled once, shared by every module.
- **Value shapes by `unit` ร `mode`.** `onChange` shapes are fully determined by the config's unit and mode (see above); segments and reasons arrive in a second `details` argument.
- **Themes are families only.** Every theme is a `{ light, dark }` pair; the v1 single-variant palettes are gone, `createTheme` always returns a family.
Prefer not to migrate composition code by hand? The [prebuilt components](#prebuilt-gallery) cover the common v2 setups with one import. Full details in [DOCUMENTATION.md](./DOCUMENTATION.md).
## Links
- ๐ [Repo Documentation](https://github.com/kirilinsky/dateforge-react-calendar/blob/main/DOCUMENTATION.md)
- ๐ [Architecture](https://github.com/kirilinsky/dateforge-react-calendar/blob/main/ARCHITECTURE.md)
- ๐ [Changelog](https://github.com/kirilinsky/dateforge-react-calendar/blob/main/CHANGELOG.md)
- ๐ [Storybook](https://kirilinsky.github.io/dateforge-react-calendar/)
- ๐ [Issues](https://github.com/kirilinsky/dateforge-react-calendar/issues)
## License
[MIT](./LICENSE) ยฉ [Kirilinsky](https://github.com/kirilinsky)