CalendarBase

Patterns

Shared Calendar Header

When to use:

• a picker needs a header with its own paging, for example a page of years with a range label

Composition notes:

• keep size and variant in the root
• render control and picker buttons inside CalendarBaseHeader, each icon button with an aria-label
• the app owns the page: move year (or start) and active together, so the grid keeps a cell in the tab order

Trade-offs:

• consistent family chrome
• still requires embedded picker logic elsewhere

import {
  CalendarBase,
  CalendarBaseControlIconButton,
  CalendarBaseHeader,
  Icon,
  Text,
  YearPicker,
  YearPickerCell,
  YearPickerLayout,
} from '@vega-ui/react';
import { ChevronLeft, ChevronRight } from '@vega-ui/icons';
import { useState } from 'react';

Shared Weekday Row

When to use:

• a derived day-grid view, such as a one-week strip, should reuse the standard weekday presentation

Composition notes:

• keep exactly seven labels and put them inside the picker, since the label row is a grid row
• align them with the embedded day grid: here both come from the same seven ISO days

Trade-offs:

• reusable and consistent
• still depends on the underlying grid logic to stay aligned

import {
  CalendarBase,
  CalendarBaseControlIconButton,
  CalendarBaseHeader,
  CalendarBaseWeekLabel,
  CalendarBaseWeekLabels,
  DayPicker,
  DayPickerItem,
  DayPickerRow,
  DayPickerRowGroup,
  Icon,
  Text,

Compact Embedded Shell

When to use:

• a calendar surface needs a tighter width footprint, such as a side panel or a card

Composition notes:

• use compact with a small size, narrow weekday names with full names in aria-label, and a short month format
• verify that the embedded picker still fits without clipping

Trade-offs:

• tighter presentation
• easier to crowd larger picker content

import {
  CalendarBase,
  CalendarBaseControlIconButton,
  CalendarBaseHeader,
  CalendarBaseWeekLabel,
  CalendarBaseWeekLabels,
  Card,
  DayPicker,
  DayPickerCell,
  DayPickerLayout,
  Heading,
  Icon,

Comparison

Quick Decision Rule

Use CalendarBase when extending the calendar subsystem itself. Use Calendar, DayPicker, MonthPicker, or YearPicker when you need actual date-selection behavior.

CalendarBase vs Calendar

• Use CalendarBase for shared shell composition.
• Use Calendar for the consumer-facing calendar subsystem.

CalendarBase vs picker components

• Use CalendarBase for shared chrome.
• Use DayPicker, MonthPicker, or YearPicker for actual grid selection behavior.

CalendarBase vs generic layout containers

• Use CalendarBase when the shell must stay aligned with the calendar-family size and variant context.
• Use Card, Sheet, or another layout primitive when the content is not actually calendar-family UI.

Choose This Component When

• you are extending calendar-family internals
• you need consistent calendar header and label chrome

Do Not Choose This Component When

• you need a ready-made picker experience
• you only need a generic panel or card layout

Troubleshooting

The Calendar Chrome Looks Right But The Picker Behavior Feels Incomplete

Symptom

The header and labels render, but the calendar does not behave like a full picker.

Likely Cause

CalendarBase was treated as a ready-made calendar instead of a shell.

How To Verify

• inspect whether an actual picker component is embedded inside the shell

Fix

Compose CalendarBase with DayPicker, MonthPicker, YearPicker, or a higher-level calendar component.

Shared Controls Do Not Match The Embedded Picker

Symptom

Header buttons or labels feel visually mismatched with the picker content below.

Likely Cause

Size or variant context drifted between the shell and the embedded picker.

How To Verify

• inspect the size and variant passed to the overall composition

Fix

Treat the shell and embedded picker as one calendar-family surface and align their shared visual context.

Compact Mode Clips Content

Symptom

The shell becomes too narrow and the embedded content feels cramped.

Likely Cause

compact was enabled for content that still needs more width.

How To Verify

• compare the same composition with and without compact

Fix

Disable compact or reduce the embedded picker density appropriately.