Calendar

Month-grid date-selection surface; owns no field, popover, or input chrome.

Distribution status

BeeUI 0.86.2-rc.3 is public on npm under the opt-in next dist-tag (observed 2026-09-25T06:25:18.371Z). latest currently resolves to 0.86.2-rc.3 and lags next until the owner moves it for all four packages. See Start for the full install commands. The import shape below works against the published package; the repository-local Registry command remains available as a no-registry-required alternative from a BeeUI checkout. Pin @0.86.2-rc.3 instead of @next for an immutable version in CI.

Identity

• Category: Forms & selection
• Status: stable public Registry/export-map component family
• Targets: iOS · Android · Web, subject to the compatibility contract
• Prerequisites: @beemvp/beeui-ui installed (or this component’s source copied via the Registry CLI below) and, on Web, the BeeUI Tailwind/Uniwind theme CSS loaded — see Start for full platform setup.
• Source: packages/ui/src/components/calendar.tsx

Import

import { Calendar } from '@beemvp/beeui-ui';

There is no documented deep/private source import. For source ownership from a BeeUI checkout:

pnpm beeui add calendar

Registry (used throughout this page) is BeeUI’s source-ownership manifest — registry/registry.json — that the pnpm beeui/@beemvp/beeui-cli CLI reads to copy a component’s real source into your app and rewrite its internal imports; it is not an npm package index. This component’s own Registry entry: registry/registry.json.

Composition and public API

• Primary export: Calendar
  • Also routed here, outside the Registry family:
    • calendar
  • Package export subpath: @beemvp/beeui-ui/calendar

Exported types: CalendarProps, CalendarVisibleMonth

The generated API inventory is mechanically joined to packages/ui/src/index.ts, Registry metadata, and the component reference contract. Each type’s field table below is parsed directly from that source, not a second hand-maintained copy; for the fuller behavior narrative see the canonical component behavior catalog.

State and behavior contract

Controlled month-grid date selection on value/onValueChange (CalendarDate | null); isDateDisabled fails a date safe as unselectable, and it owns no field, popover, or input chrome of its own.

Props

CalendarProps

Prop	Type	Default	Description
accessibilityLabel	string	—	Names the day grid for assistive tech. Defaults to the visible “Month Year” label.
className	string	—	Extra utility classes, merged after the component’s own via cn(...), so they win on conflict. An escape hatch for source-owned and application work, not a cross-engine portability guarantee.
defaultVisibleMonth	CalendarVisibleMonth	—	Initial visible month when visibleMonth is uncontrolled. Defaults to value’s month, else today’s.
direction	AnchoredOverlayDirection	—	Forces the grid’s text direction ('ltr' or 'rtl') instead of inferring it from I18nManager; also flips which arrow key/icon moves to the previous vs. next day.
disabled	boolean	false	Disables month navigation and every day cell, and stops keyboard navigation. Distinct from readOnly, which keeps the grid navigable but blocks only selection. Defaults to false.
isDateDisabled	(date: CalendarDate) => boolean	—	Marks individual dates as disabled (in addition to any min/max bounds) without disabling the whole grid.
locale	string	—	Explicit-only (ADR-008) — no ambient device/browser locale auto-detection. Defaults to 'en-US'.
max	CalendarDate	—	Latest selectable date (inclusive); later dates render disabled.
min	CalendarDate	—	Earliest selectable date (inclusive); earlier dates render disabled.
nextMonthAccessibilityLabel	string	'Next month'	Accessible label for the “next month” navigation button. Defaults to 'Next month'.
onValueChange	(date: CalendarDate) => void	—	Called with the pressed or keyboard-committed date when it is not disabled and readOnly is false.
onVisibleMonthChange	(visibleMonth: CalendarVisibleMonth) => void	—	Called whenever the visible month changes (navigation, or value moving into a different month). Required alongside visibleMonth to make it controlled; otherwise the calendar falls back to internal navigation state.
previousMonthAccessibilityLabel	string	'Previous month'	Accessible label for the “previous month” navigation button. Defaults to 'Previous month'.
readOnly	boolean	false	Keeps the grid focusable/navigable but blocks selection, distinct from disabled.
value (required)	CalendarDate | null	—	Controlled selected date. Single-date selection only for 1.0 (ADR-008).
visibleMonth	CalendarVisibleMonth	—	Controls which month/year the grid displays. Pass alongside onVisibleMonthChange to control navigation; otherwise defaults to value’s month, else today’s, and updates internally.
weekdayFormat	CalendarWeekdayFormat	'short'	Controls how weekday header labels are formatted (e.g. short vs. narrow). Defaults to 'short'.
weekStartsOn	CalendarWeekStartsOn	—	Which day starts each week row. Defaults to the convention for locale when omitted.

Also carries every prop of Omit<ViewProps, 'children' | 'role'> — that upstream contract is not reproduced here.

Related exported types:

• CalendarVisibleMonth — alias of { month: number; year: number; }.

The executable fixtures below are the source-grounded usage examples; consumers should not infer state ownership from DOM structure or another UI library.

Provider and dependencies

• BeeUIProvider is required above this family because it participates in shared overlay/toast runtime infrastructure.
• Peer/native dependencies visible to this Registry item: react, react-native
• Registry dependency closure: core-overlay, icon-button, stack, text, theme, use-direction
• Safe-area ownership remains explicit: shell surfaces touching system edges opt into SafeArea; components do not silently invent app-shell insets.
• Web consumers load the BeeUI semantic theme CSS as documented in Web onboarding.

Platform behavior

This family ships no platform-specific file, but its source branches on Platform, so some behavior differs by target.

The same public family is exposed across the supported target matrix; meaningful platform differences remain governed by the compatibility contract.

Evidence classes are not equal and this page does not blur them: Web behavior is exercised in a real browser, while iOS and Android carry package/export and native-compile evidence, which is not device-runtime proof. The compatibility contract records which class each claim rests on.

Accessibility

• Roles this family assigns: cell, grid, gridcell, row — set in calendar.tsx by the components themselves, not by the caller.
• Accessibility states and properties it sets: accessibilityElementsHidden, accessibilityLabel, accessibilityLiveRegion, disabled, hidden, selected — read from calendar.tsx.

Keyboard/focus behavior, announcements, Dynamic Type/Web zoom, RTL and reduced-motion expectations are not derived here — see Accessibility overview, Keyboard & focus, RTL/localization and Large text & zoom. BeeUI does not claim universal accessibility certification from automated tests.

Styling and theming

• Style axes: none of its own — its appearance comes from tokens and your own classes; it also carries Omit<ViewProps, 'children' | 'role'>.
• Class-name surfaces: className.

Colors, spacing and typography come from semantic tokens rather than from values written here — see Theming and Density. A className is an escape hatch for source-owned and application work, not a cross-engine portability guarantee.

Executable examples

• Primary executable fixture: apps/showcase/__tests__/calendar-selected-day-aria-selected.test.tsx
• Additional fixture: apps/showcase/__tests__/issue-172-calendar.test.tsx
• Additional fixture: apps/showcase/__tests__/issue-175-date-i18n-component-matrix.test.tsx
• Additional fixture: apps/showcase/__tests__/issue-176-calendar-date-a11y.test.tsx

Addressable examples

Each link below opens the Showcase at that exact example, not at the top of the gallery:

• basic — smallest meaningful complete usage

The Showcase links demonstrate Web behavior; use the native-preview guide for real simulator/emulator/device paths.

Live Web preview

This frame loads the real BeeUI Web Showcase on demand; it is not a second docs-only implementation. It proves browser behavior only. Use native preview for iOS/Android simulator, emulator or device paths.

Composition anatomy

• Family root / primary export: Calendar
  • Exported type surface:
    • CalendarProps
    • CalendarVisibleMonth

The tree above is ordinary document structure so it remains readable with keyboard and assistive technology; it is derived from the real public export family rather than a canvas-only diagram.

Verified example source

The following is the exact typechecked runtime Showcase fixture selected for this live preview: apps/showcase/component-gallery/public-doc-fixtures.tsx. Runtime gallery/pattern sources are preferred over test harnesses, and the displayed source and executable source are the same file; there is no separately maintained demo snippet.

import {
  Calendar,
  Card,
  FormMessage,
  Label,
  MetadataRow,
  Section,
  Text,
  useBeeToken,
  VisuallyHidden,
  VStack,
} from '@beemvp/beeui-ui';
import * as React from 'react';

/**
 * Small runtime surface for public families that are otherwise consumed only by
 * tests, private composition internals, or generated docs. Keeping these here
 * gives the public docs a real, typechecked Showcase source instead of falling
 * back to test/mock files.
 */
export function PublicDocFixtures() {
  const [date, setDate] = React.useState({ day: 3, month: 9, year: 2026 });
  const primary = useBeeToken('colors.primary');

  return (
    <VStack gap="lg" testID="public-doc-fixtures">
      <Card className="gap-4" padding="lg">
        <Section
          description="Public primitives that are normally embedded in larger application compositions."
          title="Documentation runtime fixtures"
        >
          <VStack gap="sm">
            <Label required>Project name</Label>
            <FormMessage>Example validation message</FormMessage>
            <MetadataRow
              description="Read through useBeeToken from the active Uniwind theme."
              label="colors.primary"
              value={String(primary)}
            />
            <Text testID="use-bee-token-value">
              {`useBeeToken('colors.primary') resolves to ${String(primary)} for the active theme.`}
            </Text>
            <Text>
              Visible companion text for the assistive-only content rendered immediately after it.
            </Text>
            <VisuallyHidden>
              <Text>Assistive-only VisuallyHidden fixture</Text>
            </VisuallyHidden>
          </VStack>
        </Section>
      </Card>

      <Card className="gap-4" padding="lg">
        <Section
          description="Standalone controlled Calendar using the same public API consumed by date-picker compositions."
          title="Calendar"
        >
          <Calendar onValueChange={setDate} value={date} />
        </Section>
      </Card>
    </VStack>
  );
}

Use the code block’s copy affordance to copy the exact fixture. For a smaller app-specific example, start from the public imports shown above and keep only the state your screen owns.

Limitations

• Passing visibleMonth without onVisibleMonthChange leaves the value read-only: the component renders what you passed and can never change it. It warns in development builds rather than failing silently in production.

Related

• All components
• Production patterns
• Showcase
• CLI & source ownership
• Source