Calendar Preview

1<CalendarPreview defaultMonth={new Date(2024, 3, 1)}>
2  <CalendarPreview.Days />
3</CalendarPreview>

Playground

Anatomy

Every part renders its own default, so composition is opt-in depth:

1import { CalendarPreview } from '@raystack/apsara'
2
3<CalendarPreview>
4  <CalendarPreview.Days />
5</CalendarPreview>

Expanded, the day view is a header and a grid:

1<CalendarPreview>
2  <CalendarPreview.Days>
3    <CalendarPreview.Header>
4      <CalendarPreview.Caption />
5      <CalendarPreview.Reset />
6      <CalendarPreview.PrevMonth />
7      <CalendarPreview.NextMonth />
8    </CalendarPreview.Header>
9    <CalendarPreview.Grid />
10  </CalendarPreview.Days>
11  <CalendarPreview.Footer />
12</CalendarPreview>

.Grid renders the day cells itself and takes no children. .Day and .Weekday are not written inside it — they are overrides, passed through components:

1<CalendarPreview.Grid components={{ DayButton: MyDay, Weekday: MyWeekday }} />

Children override the content a part computes from context, so <CalendarPreview.Caption>Q3 2024</CalendarPreview.Caption> replaces the month label.

API Reference

CalendarPreview

The root. Owns the selected value and the visible month, provides both to every part, and renders a column that hugs its content. Also takes render, className and ref.

CalendarPreview.Days

The day view — a header and a grid. Hugs its content rather than reserving a fixed height.

CalendarPreview.Caption

The month label above the grid, and optionally the trigger for the month and year scroller.

CalendarPreview.Grid

The day grid. Layout and per-day data live here rather than on the root, so a calendar with two grids can configure them independently.

CalendarPreview.Header

The row above the grid. Composes .Caption, .Reset, .PrevMonth and .NextMonth when given no children. Takes render, className and ref.

CalendarPreview.PrevMonth / CalendarPreview.NextMonth

Step the view one month. Never disabled by minDate or maxDate — bounds limit selection, not navigation.

CalendarPreview.Reset

Restores defaultDate, reporting reason: 'reset'. Rendered whenever defaultDate is set, and disabled once the value already equals it — it stays mounted rather than disappearing, so activating it does not send focus to the page body or shift the nav buttons sideways. It carries data-restored while there is nothing to restore.

CalendarPreview.Trigger

Anchors the popover and owns opening it. Renders the formatted value, or the placeholder, when given no children — wrap an .Input in it for a typeable field. Never renders a button, so the control inside stays focusable. Takes render, className and ref.

CalendarPreview.Content

The portaled popover surface. Takes Popover.Content props — side, align, sideOffset and the rest — and flips above the trigger on collision.

CalendarPreview.Input

CalendarPreview.Footer

The row below the calendar. A bare string is wrapped in Text; anything else renders as given.

It needs no container of its own: the root renders a column that hugs its content, so .Days and .Footer stack whatever the surrounding layout does.

useCalendar

Reads the enclosing root's state, for building parts the library does not ship. Deliberately narrow:

1import { useCalendar } from '@raystack/apsara'
2
3const { value, setValue, scale, month, setMonth, isDateUnavailable } = useCalendar()

Calling it outside a CalendarPreview throws, naming the part that asked. scale is read-only for now — the setter arrives with the scale switcher in a later phase.

setValue(null) clears the selection and reports reason: 'clear', carrying the day that was cleared as details.toDate().

Slots

Every rendered part carries a stable data-slot attribute for styling and testing:

Day cells also carry their state, so a stylesheet can target it without a class:

Examples

Composition

Each part renders a default; children replace it.

1<CalendarPreview defaultMonth={new Date(2024, 3, 1)}>
2  <CalendarPreview.Days />
3</CalendarPreview>

Reset

.Reset restores defaultDate and leaves the visible month alone — it is a value reset, not a view reset. It renders only when defaultDate is set and the current value differs from it, so the button disappears once there is nothing to restore.

defaultDate is a separate prop from defaultValue because defaultValue is ignored once value is passed. Keying the reset off its own prop is what makes it work for a controlled calendar.

defaultDate={null} is a default of nothing selected, so the button clears the day and reports reason: 'clear'. Omitting the prop is the different case: the part has no job and renders nothing.

1<CalendarPreview
2  defaultMonth={new Date(2024, 3, 1)}
3  defaultDate={new Date(2024, 3, 17)}
4  defaultValue={new Date(2024, 3, 24)}
5>
6  <CalendarPreview.Days />
7</CalendarPreview>

Selection bounds

minDate, maxDate and isDateUnavailable disable cells. None of them clamps navigation — the chevrons and the scroller still reach any month. Bounds compare whole calendar days, so a minDate carrying a time of day still leaves its own day selectable.

1<CalendarPreview
2  defaultMonth={new Date(2024, 3, 1)}
3  minDate={new Date(2024, 3, 17)}
4>
5  <CalendarPreview.Days />
6</CalendarPreview>

Grid layout

Outside days are off by default, so a grid ends on the last day of its month with the leading cells blank.

1<CalendarPreview defaultMonth={new Date(2024, 3, 1)}>
2  <CalendarPreview.Days>
3    <CalendarPreview.Header />
4    <CalendarPreview.Grid showOutsideDays />
5  </CalendarPreview.Days>
6</CalendarPreview>

Date information and tooltips

dateInfo and tooltipMessages are functions of the date, not records keyed by a formatted string. dateInfo content renders above the day number; today's dot sits below it, so the two never collide.

1<CalendarPreview defaultMonth={new Date(2024, 3, 1)}>
2  <CalendarPreview.Days>
3    <CalendarPreview.Header />
4    <CalendarPreview.Grid
5      dateInfo={(date) =>
6        date.getDate() % 7 === 0 ? (
7          <Text size="micro" variant="accent">
8            $
9          </Text>
10        ) : null
11      }
12    />
13  </CalendarPreview.Days>
14</CalendarPreview>

Month and year scroller

<CalendarPreview.Caption dropdown /> turns the caption into a filled chip that opens two adjacent scrolling columns. It is a plain popover of buttons, not a Select — picking from either column moves the view and never selects a value.

Date picker

The date picker is not a separate export — it is this composition:

1<CalendarPreview value={date} onValueChange={setDate}>
2  <CalendarPreview.Trigger>
3    <CalendarPreview.Input />
4  </CalendarPreview.Trigger>
5  <CalendarPreview.Content>
6    <CalendarPreview.Days />
7  </CalendarPreview.Content>
8</CalendarPreview>

The popover opens when the input takes focus. Enter, blur and an outside click all commit — there is no Apply button. Dismissal is Base UI's, so escape and outside press behave like every other popover in the library.

"Without calendar icon" is composition rather than a prop: pass trailingIcon={null} to .Input.

1<CalendarPreview defaultMonth={new Date(2024, 3, 1)}>
2  <CalendarPreview.Trigger>
3    <CalendarPreview.Input />
4  </CalendarPreview.Trigger>
5  <CalendarPreview.Content>
6    <CalendarPreview.Days />
7  </CalendarPreview.Content>
8</CalendarPreview>

Range selection

selection="range" turns clicks into endpoints. Give each .Input a field:

1<CalendarPreview selection="range" value={range} onValueChange={setRange}>
2  <CalendarPreview.Trigger>
3    <CalendarPreview.Input field="start" />
4    <CalendarPreview.Input field="end" />
5  </CalendarPreview.Trigger>
6  <CalendarPreview.Content>
7    <CalendarPreview.Days numberOfMonths={2} />
8  </CalendarPreview.Content>
9</CalendarPreview>

onValueChange fires on a complete range or not at all. to is not nullable, so there is no partial { from?, to? } to gate on. The half-built range stays internal — the grid styles the track from it, but nothing is emitted until the second endpoint lands.

The click machine:

Completing asks the popover to close through onOpenChange, so a consumer holding open open is not fought.

Instead of a lock prop, mark one endpoint's .Input as readOnly — the grid will not rewrite it. A read-only endpoint with no value makes the range unsatisfiable: the free endpoint sets, the range never completes, and nothing emits. Give a read-only endpoint a value.

1<CalendarPreview selection="range" defaultMonth={new Date(2024, 3, 1)}>
2  <CalendarPreview.Trigger>
3    <Flex align="center" gap={3}>
4      <CalendarPreview.Input field="start" />
5      <CalendarPreview.Input field="end" />
6    </Flex>
7  </CalendarPreview.Trigger>
8  <CalendarPreview.Content>
9    <CalendarPreview.Days numberOfMonths={2} />
10  </CalendarPreview.Content>
11</CalendarPreview>

Invalid typed dates

Typing is checked on every keystroke, and a date that fails is never committed — onValueChange does not fire and the previous value stands.

.Input marks itself aria-invalid and data-invalid, and data-invalid is what Input paints its error border from, so the field turns red on its own with nothing wired up.

onValidityChange carries a ready-to-render message, so a message under the field is one line — it is undefined while valid, which is exactly what Field's error wants:

1<Field label="Start date" error={error}>
2  <CalendarPreview>
3    <CalendarPreview.Trigger>
4      <CalendarPreview.Input onValidityChange={({ message }) => setError(message)} />
5    </CalendarPreview.Trigger>
6    <CalendarPreview.Content>
7      <CalendarPreview.Days />
8    </CalendarPreview.Content>
9  </CalendarPreview>
10</Field>

The default is a flat "Invalid input" for every reason. It stays deliberately vague because only you know the field's bounds — the component cannot say which dates would be accepted without inventing wording it has no basis for.

Override it with errorMessages, per reason. Anything left out keeps the default, so wording one reason does not mean restating the rest:

1<CalendarPreview.Input
2  errorMessages={{
3    unparseable: 'Use DD/MM/YYYY, like 15/04/2024',
4    'out-of-bounds': 'Pick a date in April 2024'
5  }}
6  onValidityChange={({ message }) => setError(message)}
7/>

The reason is also on the payload if you would rather branch on it yourself:

It fires only when validity changes, not on every keystroke, so it is safe to drive state with.

Migrating from Calendar

CalendarPreview is not a drop-in replacement. Two props keep their names and change their meaning, so they are the ones to check first — neither produces a type error in every case, and both fail quietly.

The rest are renames. Most follow the repo's conventions (onValueChange, loading, a boolean disabled), which is why the names moved rather than the behaviour:

Two things have no replacement yet: the record forms of dateInfo and tooltipMessages (both are functions here), and the classNames escape hatch — style through the data-slot attributes in the table above instead.

Slot names changed too, so a stylesheet written against Calendar needs a second set of selectors rather than an edit:

Performance

dateInfo, tooltipMessages and isDateUnavailable are functions rather than records, so the grid cannot tell a changed rule from a re-created one. Passing an inline arrow re-renders every day cell on every render of the surrounding component. Wrap them in useCallback, or hoist them out of the component, whenever the calendar is inside anything that re-renders often.

Localization

English only for now. There is no locale prop: month and weekday names come from date-fns' default en-US, and the nav, reset and caption labels are hardcoded strings. timeZone is unaffected — a calendar can render in any zone, in English. Localization is tracked against RFC 005 rather than patched in per-part.

Accessibility

• Arrow keys move between days; the focused cell carries data-draft until it is committed
• readOnly is conveyed with aria-readonly on the grid and aria-disabled on each day, and the grid stays focusable and arrow-navigable — unlike disabled
• Each grid is labelled with its month, so the caption is not the only announcement
• Nav buttons carry aria-label, and the scroller's columns are labelled groups
• Selected and unavailable days are announced through their native button state