Build exactly the calendar your product needs.

Quick start

No global CSS import is required. Every module ships its own styles and applies them on first render. In RSC frameworks, render the calendar behind a "use client" boundary.

Core idea

DateForge is a stateful composition wrapper with self-contained modules. Behavior is compiled once with createCalendarConfig({ mode, unit, locale, min, max, disabled, … }) and passed to the <Calendar> shell as a single config prop. The shell owns the value, view date, theme, appearance, scheme, and onChange wiring. It renders no picker UI by itself.

Visible behavior comes from modules placed as children: CalendarToolbar, CalendarDays, CalendarTimeWheel, CalendarPresets, CalendarSelectedDates, manual input, and track modules. You mount only the UI your product needs.

The wrapper also provides a small grid contract: cols defines equal parent tracks, and child col={number} spans that many tracks. For example, inside cols={4}, a module with col={2} takes half the row. col is a span count, not CSS grid-line syntax.

Since 3.1, a numeric cols={N} is responsive: it renders up to N equal columns and collapses toward one on narrow screens. The collapse threshold is the --cal-cols-min CSS variable (default 14em) — set it to 0px for fixed, never-collapsing tracks. col="full" places a module across the entire row, collapse-safely. String cols values stay raw grid-template-columns and never collapse.

When not to use DateForge

DateForge is a picker composition kit, not a full calendar application or a date utility library. It is strongest when your product needs a custom date, range, or date-time picker built from small React modules.

Choose something simpler or more specialized when:

• You only need a native browser field like <input type="date">, <input type="time">, or <input type="datetime-local">.
• You want one prebuilt picker with almost no composition decisions, styling decisions, or module choices.
• You need event-calendar features: drag-and-drop events, resource columns, agenda views, recurring events, ICS import/export, or meeting scheduling logic.
• You need general date math, timezone conversion, parsing, or formatting utilities. Pair DateForge with Temporal, date-fns, dayjs, or your app's existing date layer for that work.
• You need a non-React widget, a server-rendered-only calendar, or a framework-agnostic web component.
• You need a full form field abstraction with labels, validation messages, popovers, input masks, and form-library bindings already bundled.

Modules

Modules read calendar context directly, so there is no prop drilling. They can be reordered, repeated, or used alone. Any subset should render without crashing, but not every subset is a complete human-friendly UX.

Selection model: unit × mode

Two config axes decide the value shape and selection semantics: unit ("day" | "week" | "month", default "day") and mode ("single" | "multiple" | "range" | "multi-range", default "single"). The onChange shape is fully determined by the pair:

Spans are always emitted complete — while the user is still drawing a range, the value stays null (or keeps the previous committed span). onChange also receives a second details argument (CalendarChangeDetails) with reason and segments — the business-day cut when exclude/disabled rules apply. Caps and lengths live in the config too: minSpan/maxSpan (in units), maxDates for multiple, maxRanges for multi-range.

Which modules do I need?

Start from the product workflow, then pick modules. The calendar does not force one canonical picker.

Import strategy

The package is split into tree-shakeable subpaths. The aggregate paths are convenient for prototyping; per-subpath imports keep production bundles small.

Built-in themes and appearances can also be referenced by plain string name (theme="dracula", appearance="zenith") — the generated stylesheet resolves them at runtime. Strings keep every palette reachable; imported objects tree-shake to just the ones you use.

Toolbar imports — all toolbar primitives ship together on one subpath (the module is one bundle; unused primitives tree-shake out):

Module imports - two patterns:

Performance with multiple calendars

Three or more visible calendars are reasonable, but treat them as a layout and state-design decision. Most slowdowns come from mounting more modules than the screen needs, recreating config objects on every parent render, or rendering several independent providers when one shared calendar state would do.

For a year-style picker, prefer one <Calendar> with multiple offset nav/day pairs instead of twelve separate calendars:

Keep expensive props stable when the parent rerenders:

• Compile the config once: useMemo(() => createCalendarConfig({...}), [...]) or module scope. A new config object on every render forces every module to re-read state.
• Keep custom presets, theme, and appearance objects outside render or behind useMemo.
• Mount only the modules the current surface needs; avoid three CalendarTimeWheel or track stacks unless all are visible and interactive.
• Import theme/appearance objects from the barrels for production bundles; string names keep the full generated stylesheet reachable.
• In long forms, consider mounting the picker only when its popover, tab, or step is active.

Measure in production mode on the target device class. Dev mode and React Strict Mode exaggerate render work.

Useful checks:

• React DevTools Profiler: record initial mount, next/previous month, day selection, range hover, and preset click.
• Chrome Performance panel: throttle CPU, record the same interactions, and watch scripting time plus input delay.
• Browser Performance API: wrap product-specific work inside performance.mark() and performance.measure() around handlers that react to onChange.
• Bundle inspection: compare aggregate imports against per-theme and per-appearance subpaths when bundle size matters.
• Real user metrics: watch INP and long tasks on pages where calendars are visible by default.

When does each action fire onChange?

The rule of thumb is simple: navigation changes the view, selection commits values.

readOnly blocks every selection-affecting action, but navigation stays enabled. UI-only state like popup open/close and theme toggles does not fire onChange.

Controlled and uncontrolled

Controlled mode starts when value is provided, including null. User actions fire onChange with the next value, but rendered selection stays tied to the value you pass back.

Uncontrolled mode starts when value is undefined. defaultValue seeds the reducer once on mount, internal state owns future changes, and onChange still fires.

When both value and defaultValue are passed, value wins. If you swap in a config with a different unit/mode at runtime, pass a compatible value at the same time; selection shape is not migrated for you.

Accessibility labels

DateForge ships English aria-label defaults for icon buttons, toolbars, dialogs, spinbuttons, tracks, and overflow controls. In v3 they live in one labels registry instead of dozens of per-component props. Resolution is tiered: module prop → root labels → English default.

Pass a partial registry to <Calendar labels={...}> to localize globally; a handful of modules keep small per-instance overrides (e.g. clearLabel on CalendarSelectedDates, weekLabel on CalendarDays).

Templated labels keep their placeholder names — DateForge interpolates {month}, {year}, {time}, {period}, {count}, {date}, {from}, and {to} where the module has that value available.

Registry keys by area:

The exact LabelOverrides type ships with the package — your editor autocompletes every key.

Ready-made module sets

These are starting points rather than exported presets. Copy the shape, then add constraints, disabled rules, themes, or appearances.

Minimal single date

Booking range

Analytics range with presets

Date and time

Mobile tracks

Prebuilt components

Skip composition entirely: @dateforge/react-calendar/prebuilt ships four ready recipes over the same primitives, with plain-Date props (value, defaultValue, onChange, locale, min/max, disabled, readOnly, theme, appearance, gradient, scheme, and a config escape hatch for extra createCalendarConfig options).

SimpleCalendar

The default calendar: month/year navigation header + day grid, single-date selection. One import and done.

DatePicker

Typed, segment-based manual input above the calendar, plus a Today jump — keyboard-first single-date entry with the grid as fallback. allowClear (default true) controls the clear button inside the manual input — pass false to hide it.

MonthPicker

Year-stepping header + 12-month grid; picking a month selects the whole month (unit: "month" under the hood), reported as its first day.

MultiMonthCalendar

3, 6, or 12 consecutive months in a grid, generated on the fly. One shared selection spans the whole board — ranges drag across months. Prev/next arrows on the first and last header step the whole board.

When a prebuilt stops fitting, drop one level down to the modules — every prebuilt is just Calendar + modules + createCalendarConfig inside.

Week and month selection

unit switches what one click selects. unit: "week" selects whole weeks, unit: "month" whole months — both emit { start, end } spans:

Multiple ranges

mode: "multi-range" collects several { start, end } spans, capped by maxRanges. CalendarSelectedDates renders one chip pair per span with per-chip removal:

Business days: exclude

exclude keeps days spannable but cuts them from the emitted value — the classic "10 business days" flow. onChange details report the resulting segments:

Time, time zones, and DST

withTime adds a time of day to selected values; minTime/maxTime clamp the selectable window in the core (wheels, toolbar time, and manual input all respect it):

timeZone pins "today" resolution to an IANA zone, DST-safe, with explicit policies for ambiguous and nonexistent wall-clock times:

Module reference

Calendar

The root wrapper and context provider. Owns all shared state - mode, value, view date, locale, timezone, theme, appearance, disabled rules, and range constraints - and distributes it to every child module via context. Renders no UI of its own; all visible output comes from the modules you place inside it.

createCalendarConfig

Everything behavioral lives in the config — compiled once, shared by every module:

CalendarToolbar

Composable navigation bar. Place sub-components as children to compose exactly the toolbar your product needs. Controls the internal viewDate - does not commit selection.

The default layout (no cols) is a wrapping flex row: overflow wraps to the next line instead of escaping the container, rows distribute space-between, and an over-wide label shrinks with an ellipsis. Passing cols switches to the explicit grid mode, which never wraps.

Sub-components (all imported from @dateforge/react-calendar/modules/toolbar):

CalendarDays

The main day grid. Renders a month view and commits selection on click. Works across all three modes - single, multiple, and range - adapting highlight and click semantics automatically.

CalendarTimeWheel

Drum-scroll time picker for hours, minutes, and optionally seconds. Pairs with CalendarDays for a full date-time picker, or stands alone as a time-only input with createCalendarConfig({ withTime: true }).

CalendarPresets

Shortcut buttons that jump to predefined dates or ranges with a single click. Presets are explicit: pass your own array, commonPresets, relativePresets, or individual exports like presetToday / presetLast7Days. If presets is omitted or empty, the module renders no buttons.

See custom presets - simple and advanced definitions →

CalendarSelectedDates

Renders the current selection as chips. In range mode shows from/to bounds; in multiple mode shows one chip per date. Chips can navigate to their date or clear individual entries.

CalendarManualInput

Free-text date input that parses typed values and syncs them with calendar state. Useful when users know the exact date and prefer typing over clicking.

CalendarInfo

Read-only summary of the current selection. In single mode prints the date; in multiple prints a count and list; in range prints the bounds plus a duration or day count. Use to surface "facts about the value" - relative time, range length, ISO summary - without rebuilding selection chips. Pass a formatter for fully custom output.

CalendarDaysTrack

Horizontal drum scroller for day selection. Designed for mobile-first layouts. Use bound to tie each drum to the from or to side of a range independently.

CalendarMonthsTrack

Drum scroller for month navigation. Scrolling moves the internal viewDate without committing selection. Combine with CalendarDaysTrack for a full mobile drum picker.

CalendarYearsTrack

Drum scroller for year navigation. Works the same way as CalendarMonthsTrack but scrolls through years. Stack all three track modules for a compact iOS-style date picker.

CalendarMonthsGrid

12-cell month grid for month-only pickers or fast month navigation. Clicking a cell moves viewDate to that month. Use onMonthSelect to build a standalone month picker without CalendarDays.