Calendar

A versatile calendar component for React & React Native with support for single, multiple, and range date selection. Features include event markers, disabled dates, week numbers, and customizable styling. This is an illustration of Calendar component.

Basic Calendar

A simple calendar component with single date selection

Installation

Run the following command:

npx gluestack-ui@alpha add calendar

API Reference

To use this component in your project, include the following import statement in your file.

import {
  Calendar,
  CalendarHeader,
  CalendarHeaderPrevButton,
  CalendarHeaderNextButton,
  CalendarHeaderTitle,
  CalendarHeaderMonthSelect,
  CalendarHeaderYearSelect,
  CalendarWeekDaysHeader,
  CalendarWeekDay,
  CalendarBody,
  CalendarGrid,
  CalendarWeek,
  CalendarDay,
  CalendarDayText,
  CalendarDayIndicator,
  CalendarWeekNumber,
  CalendarFooter,
} from '@/components/ui/calendar';

Component Anatomy

export default () => (
  <Calendar>
    <CalendarHeader>
      <CalendarHeaderPrevButton />
      <CalendarHeaderMonthSelect />
      <CalendarHeaderYearSelect />
      <CalendarHeaderTitle />
      <CalendarHeaderNextButton />
    </CalendarHeader>
    <CalendarWeekDaysHeader>
      <CalendarWeekDay />
    </CalendarWeekDaysHeader>
    <CalendarBody>
      <CalendarGrid>
        <CalendarWeek>
          <CalendarWeekNumber />
          <CalendarDay>
            <CalendarDayText />
            <CalendarDayIndicator />
          </CalendarDay>
        </CalendarWeek>
      </CalendarGrid>
    </CalendarBody>
    <CalendarFooter />
  </Calendar>
);

Calendar Props

Contains all the calendar related layout style props and actions.

Prop	Type	Default	Description
mode	'single' \| 'multiple' \| 'range'	'single'	Selection mode for the calendar.
value	Date \| Date[] \| { from: Date; to?: Date }	-	Controlled value of the calendar.
defaultValue	Date \| Date[] \| { from: Date; to?: Date }	-	Default value for uncontrolled calendar.
onValueChange	(value) => void	-	Callback when selection changes.
minDate	Date	-	Minimum selectable date.
maxDate	Date	-	Maximum selectable date.
disabledDates	Date[] \| (date: Date) => boolean	-	Disabled dates or function to check disabled dates.
initialMonth	Date	-	Initial month to display.
numberOfMonths	number	1	Number of months to display.
showWeekNumbers	boolean	false	Show ISO week numbers.
showOutsideDays	boolean	true	Show days from adjacent months.
firstDayOfWeek	0-6	0	First day of week (0=Sunday).
fixedWeeks	boolean	false	Always show 6 weeks.
markers	CalendarMarkers	-	Event markers for specific dates.
enableMonthYearPicker	boolean	false	Enable month/year dropdown selectors.
minYear	number	-	Minimum year in year picker.
maxYear	number	-	Maximum year in year picker.
locale	string	'en-US'	Locale for date formatting.
isDisabled	boolean	false	Disable entire calendar.
isReadOnly	boolean	false	Read-only mode.
onMonthChange	(month: Date) => void	-	Called when month changes.
onDayPress	(date: Date) => void	-	Called when day is pressed.
onDayLongPress	(date: Date) => void	-	Called when day is long-pressed.

Marker Types

Markers allow you to add visual indicators to dates.

Type	Description
dot	Single colored dot below the date.
multi-dot	Multiple colored dots below the date.
period	Highlighted period/background for the date.

Marker Colors

Marker colors support shadcn-style design tokens using CSS variables:

const markers = {
  '2024-01-15': {
    type: 'dot',
    color: 'hsl(var(--primary))', // Primary color
  },
  '2024-01-20': {
    type: 'multi-dot',
    dots: [
      { color: 'hsl(var(--primary))', key: '1' },
      { color: 'hsl(var(--destructive))', key: '2' },
    ],
  },
  '2024-01-25': {
    type: 'period',
    color: 'hsl(var(--secondary))', // Secondary color
  },
};

Available color tokens:

hsl(var(--primary))

- Primary brand color

hsl(var(--secondary))

- Secondary color

hsl(var(--accent))

- Accent color

hsl(var(--destructive))

- Destructive/error color

hsl(var(--muted))

- Muted/neutral color

Sub-components

CalendarHeader

Container for the calendar header. Contains navigation buttons and title.

CalendarHeaderPrevButton / CalendarHeaderNextButton

Navigation buttons for moving between months. Use with Icon component.

CalendarHeaderTitle

Displays the current month and year.

CalendarHeaderMonthSelect / CalendarHeaderYearSelect

Dropdown selectors for quick month/year navigation. Requires

enableMonthYearPicker={true}

CalendarWeekDaysHeader

Container for the weekday labels row (Sun, Mon, Tue, etc.).

CalendarWeekDay

Individual weekday label cell.

CalendarBody

Container for the calendar body.

CalendarGrid

Grid container for the calendar days.

CalendarWeek

Individual week row container.

CalendarDay

Individual day cell. Supports

data-state

attribute for styling based on state.

CalendarDayText

Text component for displaying the day number. Automatically styles based on day state.

CalendarDayIndicator

Visual indicator for event markers. Use with

data-type

attribute.

CalendarWeekNumber

Displays ISO week numbers when

showWeekNumbers={true}

CalendarFooter

Footer container for additional content.

Features

Three Selection Modes: Single date, multiple dates, and date range selection

Event Markers: Dot, multi-dot, and period indicators for dates

Date Constraints: Min/max dates and custom disabled dates

Week Numbers: Optional ISO week number display

Month/Year Picker: Quick navigation with dropdown selectors

Customizable: Full Tailwind CSS styling support with shadcn-style tokens

Accessible: Built-in disabled and read-only states

Internationalization: Locale support via date-fns

Styling

The Calendar component uses shadcn-style design tokens for consistent theming. These semantic color tokens automatically adapt to light and dark modes.

Available Color Tokens

| Token | Light Mode | Dark Mode | Usage | | --------------------------- | ----------- | ---------- | ------------------------------- | |

bg-primary

text-primary-foreground

bg-secondary

text-secondary-foreground

bg-accent

text-accent-foreground

bg-destructive

bg-background

text-foreground

text-muted-foreground

border-border

| Light gray | Dark gray | Borders |

Usage Example

<Calendar className="bg-card border border-border">
  <CalendarHeader className="bg-accent rounded-t-lg">
    <CalendarHeaderTitle className="text-accent-foreground font-bold" />
  </CalendarHeader>
  <CalendarBody className="bg-background">
    <CalendarGrid />
  </CalendarBody>
</Calendar>

State-based Styling

Day cells automatically receive state attributes for styling:

data-state="selected"

- Selected date

data-state="today"

- Today's date

data-state="disabled"

- Disabled date

data-state="outside-month"

- Date from adjacent month

data-state="range-start"

data-state="range-end"

data-state="range-middle"

- Range selection states

Accessibility

Tab: Move focus between interactive elements

Enter/Space: Select a date or activate buttons

Arrow Keys: Navigate between dates (when focus is within calendar)

The calendar announces the current month, selected date(s), and day names appropriately.

ARIA Attributes

Dates have appropriate role and aria-label attributes

Selected dates are marked with aria-selected

Disabled dates have aria-disabled

Examples

The Examples section provides visual representations of the different variants of the component, allowing you to quickly and easily determine which one best fits your needs.

Selection Modes

Calendar supports three selection modes: single date, multiple dates, and date range selection

mode

Month & Year Picker

Enable quick navigation with month and year dropdown selectors

With Event Markers

Add visual indicators and markers to highlight specific dates with events or important information

With Disabled Dates

Disable specific dates or date ranges using minDate, maxDate, or custom disabled dates function

With Week Numbers

Display ISO week numbers alongside the calendar for business and project planning use cases

Customized Styling

Customize the calendar appearance with different sizes, colors, and styles using Tailwind classes

size

Edit this page on GitHub

Go backDateTimePicker

Up nextFormControl