CalendarBase

Summary

CalendarBase is the shared layout and context foundation for the VegaUI calendar family. It provides size, variant, and compactness to shared header, picker-button, control-button, and weekday-label parts, but it is not a complete date-selection widget on its own.

Imports

import {
  CalendarBase,
  CalendarBaseControlIconButton,
  CalendarBaseHeader,
  CalendarBasePickerButton,
  CalendarBaseWeekLabel,
  CalendarBaseWeekLabels,
  type CalendarBaseControlIconButtonProps,
  type CalendarBaseHeaderProps,
  type CalendarBasePickerButtonProps,
  type CalendarBaseProps,
  type CalendarBaseSize,
  type CalendarBaseVariant,
  type CalendarBaseWeekLabelProps,
  type CalendarBaseWeekLabelsProps,
} from '@vega-ui/react';

Exported Types

• CalendarBaseProps
• CalendarBaseHeaderProps
• CalendarBaseWeekLabelsProps
• CalendarBaseWeekLabelProps
• CalendarBasePickerButtonProps
• CalendarBaseControlIconButtonProps
• CalendarBaseVariant
• CalendarBaseSize

Minimal Composition

import {
  CalendarBase,
  CalendarBaseHeader,
  CalendarBaseWeekLabel,
  CalendarBaseWeekLabels,
  DayPicker,
  DayPickerCell,
  DayPickerLayout,
  Text,
} from '@vega-ui/react';

const weekdays = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];

Required Parts

• CalendarBase: root layout and shared calendar context

Optional Parts

• CalendarBaseHeader
• CalendarBasePickerButton
• CalendarBaseControlIconButton
• CalendarBaseWeekLabels
• CalendarBaseWeekLabel
• embedded picker content from DayPicker, MonthPicker, YearPicker, or custom calendar-family wrappers

Composition Order

1. CalendarBase
2. optional CalendarBaseHeader
3. optional week-label row
4. embedded picker/grid content

Variants

• Variant: primary or secondary
• Size: xs, sm, md, lg, xl
• Density: default or compact

Edge Cases

• CalendarBase is primarily a subsystem primitive, not the main consumer-facing calendar surface.
• Size and variant should stay aligned across header and embedded picker content.
• compact changes layout density but not the actual date logic.
• It should stay visually aligned with picker layers rather than becoming a separate theme or layout system.

Common Mistakes

• Treating CalendarBase like a complete calendar widget.
• Rebuilding shared calendar header parts manually instead of using the exported pieces.
• Letting custom variants drift from the rest of the calendar family.

Examples

Basic

Basic: day calendar from base parts

CalendarBase is the shell for a calendar the app builds itself: it passes size and variant to the header buttons and weekday labels, and the app owns the month. The weekday row sits inside DayPicker, because it is a grid row, and its order matches weekStartsOn of the layout. DayPicker keeps its active cell when month changes, so the example moves active together with the month to keep a cell in the tab order.

import {
  CalendarBase,
  CalendarBaseControlIconButton,
  CalendarBaseHeader,
  CalendarBaseWeekLabel,
  CalendarBaseWeekLabels,
  DayPicker,
  DayPickerCell,
  DayPickerLayout,
  Icon,
  Text,
} from '@vega-ui/react';

Controlled/Stateful

Controlled/Stateful: header with dynamic labels

One CalendarBasePickerButton switches between the days and the months and reports the state with aria-pressed; the labels of the previous / next buttons change with the view, because the same buttons step by a month or by a year.

import {
  CalendarBase,
  CalendarBaseControlIconButton,
  CalendarBaseHeader,
  CalendarBasePickerButton,
  CalendarBaseWeekLabel,
  CalendarBaseWeekLabels,
  DayPicker,
  DayPickerCell,
  DayPickerLayout,
  Icon,
  MonthPicker,

Layout/Overlay

Layout/Overlay: two months in one shell

Two DayPickerLayouts inside one DayPicker let a range cross the month boundary; distinct offsets keep their row indexes unique. Each month gets its own weekday row and an aria-label on its row group, so the visible month titles can stay hidden from screen readers.

import {
  CalendarBase,
  CalendarBaseControlIconButton,
  CalendarBaseHeader,
  CalendarBaseWeekLabel,
  CalendarBaseWeekLabels,
  DayPicker,
  DayPickerCell,
  DayPickerLayout,
  Icon,
  Text,
} from '@vega-ui/react';

Disabled

Disabled: navigation within a window

from and to on DayPicker disable the days outside the window, and the app disables the previous / next buttons at its first and last month. The rule is written next to the grid and linked with aria-describedby.

import {
  CalendarBase,
  CalendarBaseControlIconButton,
  CalendarBaseHeader,
  CalendarBaseWeekLabel,
  CalendarBaseWeekLabels,
  DayPicker,
  DayPickerCell,
  DayPickerLayout,
  HelperText,
  Icon,
  Text,

Edge

Edge: compact weekday labels

Narrow weekday names repeat letters in many locales (S, M, T, W, T, F, S), so each label gets the full name in aria-label. compact with size='xs' keeps the shell as narrow as the grid.

import {
  CalendarBase,
  CalendarBaseWeekLabel,
  CalendarBaseWeekLabels,
  DayPicker,
  DayPickerCell,
  DayPickerLayout,
} from '@vega-ui/react';

const LOCALE = 'en-US';
const WEEK_START = 0;
const narrowFormat = new Intl.DateTimeFormat(LOCALE, { weekday: 'narrow', timeZone: 'UTC' });

Edge: right-to-left shell

dir='rtl' on CalendarBase mirrors the header and the grid, but the base parts do not swap icons: the "previous" button needs a right-pointing chevron and the "next" button a left-pointing one. The Calendar navigation buttons flip their chevrons by themselves.

import {
  CalendarBase,
  CalendarBaseControlIconButton,
  CalendarBaseHeader,
  CalendarBaseWeekLabel,
  CalendarBaseWeekLabels,
  DayPicker,
  DayPickerCell,
  DayPickerLayout,
  Icon,
  Text,
} from '@vega-ui/react';

Anatomy

Overview

CalendarBase provides the shared visual shell for calendar-family components. It supplies context to shared header, control buttons, picker buttons, and weekday labels.

Required Parts

CalendarBase

Required. Owns shared size, variant, and compactness.

Optional Parts

CalendarBaseHeader

Optional header row for navigation and picker triggers.

CalendarBasePickerButton

Optional button for month/year picker toggles.

CalendarBaseControlIconButton

Optional previous/next control button.

CalendarBaseWeekLabels

Optional row wrapper for weekday labels.

CalendarBaseWeekLabel

Optional weekday header cell.

Composition Order

1. CalendarBase
2. optional CalendarBaseHeader
3. embedded picker content
4. optional CalendarBaseWeekLabels, inside the picker before its rows: the label row has role='row' and belongs to the grid

Valid Composition Patterns

A working day calendar: the header with icon buttons and a month label, then a DayPicker that holds the weekday row and the layout. The app keeps the visible month and the active day.

import {
  CalendarBase,
  CalendarBaseControlIconButton,
  CalendarBaseHeader,
  CalendarBaseWeekLabel,
  CalendarBaseWeekLabels,
  DayPicker,
  DayPickerCell,
  DayPickerLayout,
  Icon,
  Text,
} from '@vega-ui/react';

Invalid Composition Patterns

Shared calendar parts rendered outside CalendarBase

They lose the size and variant context that keeps the family consistent.

Consumer-facing calendar built from base parts without reusing the family behavior

The visual shell may match, but interaction and semantics can drift from the higher-level calendar components.