# Calendar

**📖 Live documentation:** https://cds.coinbase.com/components/other/Calendar/

Calendar is a flexible, accessible date grid component for selecting dates, supporting keyboard navigation, disabled/highlighted dates, and custom rendering.

## Import

```tsx
import { Calendar } from '@coinbase/cds-web/dates/Calendar'
```

## Examples

Calendar is a date grid for selecting dates and powers the picker in [DatePicker](/components/other/DatePicker). Control the visible month with `selectedDate` or `seedDate`, and use `onPressDate` to handle selection. It supports keyboard navigation, disabled and highlighted dates, and custom styling via `classNames` and `styles`.

### Basics

#### Basic usage

```tsx live
() => {
  const [selectedDate, setSelectedDate] = useState(new Date());
  return <Calendar selectedDate={selectedDate} onPressDate={setSelectedDate} />;
};
```

### Disabled dates

```tsx live
() => {
  const [selectedDate, setSelectedDate] = useState(new Date());
  // Disable today and tomorrow
  const today = new Date();
  const tomorrow = new Date(today);
  tomorrow.setDate(today.getDate() + 1);
  return (
    <Calendar
      selectedDate={selectedDate}
      onPressDate={setSelectedDate}
      disabledDates={[today, tomorrow]}
      disabledDateError="This date is not selectable."
    />
  );
};
```

### Highlighted dates

```tsx live
() => {
  const [selectedDate, setSelectedDate] = useState(new Date());
  // Highlight the 10th, 15th, and 20th of the current month
  const now = new Date();
  const year = now.getFullYear();
  const month = now.getMonth();
  const highlightedDates = [
    new Date(year, month, 10),
    new Date(year, month, 15),
    new Date(year, month, 20),
  ];
  return (
    <Calendar
      selectedDate={selectedDate}
      onPressDate={setSelectedDate}
      highlightedDates={highlightedDates}
    />
  );
};
```

### Styling

#### Slot styling

Use the `classNames` and `styles` props to target specific elements: `root`, `header`, `monthLabel`, `navArrows` (container), `navArrow` (each button), `dayHeader`, `content` (day header + date grid), `calendarGrid` (date cells container), and `dayCell`.

```tsx live
() => {
  const [selectedDate, setSelectedDate] = useState(new Date());
  const highlightedDates = useMemo(() => {
    const d = new Date();
    d.setDate(d.getDate() - 1);
    return [d];
  }, []);
  const disabledDates = useMemo(() => {
    const d = new Date();
    d.setDate(d.getDate() - 2);
    return [d];
  }, []);
  return (
    <>
      <style>{`
        .calendar-slot-demo-nav-arrow [data-icon-name] {
          color: var(--color-bgNegative);
        }
        .calendar-slot-day-header span {
          color: var(--color-bgNegative);
        }
        .calendar-slot-day-cell[aria-pressed="true"] {
          background-color: var(--color-bgWarning);
          border-color: var(--color-bgWarning);
        }
        .calendar-slot-day-cell[aria-current="date"] {
          border-color: var(--color-accentBoldYellow);
        }
        .calendar-slot-day-cell[aria-disabled="true"] {
          background-color: var(--color-bgDisabled);
          border-color: var(--color-bgDisabled);
        }
        .calendar-slot-day-cell[aria-disabled="true"] span {
          color: var(--color-bgPositive);
        }
        .calendar-slot-day-cell[data-highlight="true"] {
          background-color: var(--color-bgPositiveWash);
          border-color: var(--color-bgPositive);
        }
        .calendar-slot-day-cell[data-highlight="true"] span {
          color: var(--color-fg);
        }
      `}</style>
      <Calendar
        selectedDate={selectedDate}
        onPressDate={setSelectedDate}
        disabledDates={disabledDates}
        highlightedDates={highlightedDates}
        classNames={{
          navArrow: 'calendar-slot-demo-nav-arrow',
          dayHeader: 'calendar-slot-day-header',
          dayCell: 'calendar-slot-day-cell',
        }}
        styles={{
          root: {
            backgroundColor: 'var(--color-bgAlternate)',
            borderRadius: 16,
            borderColor: 'var(--color-bgLinePrimary)',
            borderWidth: 'medium',
          },
          header: {
            paddingBottom: 0,
            backgroundColor: 'var(--color-bgPositiveWash)',
            borderRadius: 16,
          },
          monthLabel: { color: 'var(--color-fgPrimary)' },
          navArrows: { border: 'medium dashed var(--color-bgLine)', borderRadius: 8 },
          navArrow: { backgroundColor: 'transparent', borderColor: 'transparent' },
          calendarGrid: { paddingBottom: 8, paddingTop: 8 },
          dayCell: { borderRadius: 8 },
        }}
      />
    </>
  );
};
```

### Accessibility

Use `nextArrowAccessibilityLabel` and `previousArrowAccessibilityLabel` so screen reader users can navigate months. When using `disabledDates`, `minDate`, or `maxDate`, provide `disabledDateError` so users understand why a date cannot be selected.

```tsx live
() => {
  const [selectedDate, setSelectedDate] = useState(new Date());
  const nextMonth = useMemo(() => {
    const d = new Date();
    d.setMonth(d.getMonth() + 1);
    return d;
  }, []);
  return (
    <Calendar
      selectedDate={selectedDate}
      onPressDate={setSelectedDate}
      maxDate={nextMonth}
      disabledDateError="Date is not available for selection"
      nextArrowAccessibilityLabel="Go to next month"
      previousArrowAccessibilityLabel="Go to previous month"
      highlightedDateAccessibilityHint="Highlighted"
    />
  );
};
```

## Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `alignContent` | `ResponsiveProp<center \| normal \| start \| end \| flex-start \| flex-end \| stretch \| baseline \| first baseline \| last baseline \| space-between \| space-around \| space-evenly>` | No | `-` | - |
| `alignItems` | `ResponsiveProp<center \| normal \| start \| end \| flex-start \| flex-end \| self-start \| self-end \| stretch \| baseline \| first baseline \| last baseline>` | No | `-` | - |
| `alignSelf` | `ResponsiveProp<center \| normal \| auto \| start \| end \| flex-start \| flex-end \| self-start \| self-end \| stretch \| baseline \| first baseline \| last baseline>` | No | `-` | - |
| `as` | `div` | No | `-` | The underlying element or component the polymorphic component will render.  Changing as also changes the inherited native props (e.g. href for as=a) and the expected ref type. |
| `aspectRatio` | `ResponsiveProp<AspectRatio>` | No | `-` | - |
| `background` | `ResponsiveProp<Color>` | No | `-` | - |
| `borderBottomLeftRadius` | `ResponsiveProp<BorderRadius>` | No | `-` | - |
| `borderBottomRightRadius` | `ResponsiveProp<BorderRadius>` | No | `-` | - |
| `borderBottomWidth` | `ResponsiveProp<BorderWidth>` | No | `-` | - |
| `borderColor` | `ResponsiveProp<Color>` | No | `-` | - |
| `borderEndWidth` | `ResponsiveProp<BorderWidth>` | No | `-` | - |
| `borderRadius` | `ResponsiveProp<BorderRadius>` | No | `-` | - |
| `borderStartWidth` | `ResponsiveProp<BorderWidth>` | No | `-` | - |
| `borderTopLeftRadius` | `ResponsiveProp<BorderRadius>` | No | `-` | - |
| `borderTopRightRadius` | `ResponsiveProp<BorderRadius>` | No | `-` | - |
| `borderTopWidth` | `ResponsiveProp<BorderWidth>` | No | `-` | - |
| `borderWidth` | `ResponsiveProp<BorderWidth>` | No | `-` | - |
| `bordered` | `boolean` | No | `-` | Add a border around all sides of the box. |
| `borderedBottom` | `boolean` | No | `-` | Add a border to the bottom side of the box. |
| `borderedEnd` | `boolean` | No | `-` | Add a border to the trailing side of the box. |
| `borderedHorizontal` | `boolean` | No | `-` | Add a border to the leading and trailing sides of the box. |
| `borderedStart` | `boolean` | No | `-` | Add a border to the leading side of the box. |
| `borderedTop` | `boolean` | No | `-` | Add a border to the top side of the box. |
| `borderedVertical` | `boolean` | No | `-` | Add a border to the top and bottom sides of the box. |
| `bottom` | `ResponsiveProp<Bottom<string \| number>>` | No | `-` | - |
| `classNames` | `{ readonly root?: string; readonly header?: string \| undefined; readonly title?: string \| undefined; readonly navigation?: string \| undefined; readonly content?: string \| undefined; readonly day?: string \| undefined; } \| undefined` | No | `-` | - |
| `color` | `ResponsiveProp<Color>` | No | `-` | - |
| `columnGap` | `ResponsiveProp<Space>` | No | `-` | - |
| `dangerouslySetBackground` | `string` | No | `-` | - |
| `disabled` | `boolean` | No | `-` | Disables user interaction. |
| `disabledDateError` | `string` | No | `'Date unavailable'` | Tooltip content shown when hovering or focusing a disabled date, including dates before the minDate or after the maxDate. |
| `disabledDates` | `(Date \| [Date, Date])[]` | No | `-` | Array of disabled dates, and date tuples for date ranges. Make sure to set disabledDateError as well. A number is created for every individual date within a tuple range, so do not abuse this with massive ranges. |
| `display` | `ResponsiveProp<grid \| revert \| none \| block \| inline \| inline-block \| flex \| inline-flex \| inline-grid \| contents \| flow-root \| list-item>` | No | `-` | - |
| `elevation` | `ResponsiveProp<Elevation>` | No | `-` | - |
| `flexBasis` | `ResponsiveProp<FlexBasis<string \| number>>` | No | `-` | - |
| `flexDirection` | `ResponsiveProp<column \| row \| row-reverse \| column-reverse>` | No | `-` | - |
| `flexGrow` | `ResponsiveProp<FlexGrow>` | No | `-` | - |
| `flexShrink` | `ResponsiveProp<FlexShrink>` | No | `-` | - |
| `flexWrap` | `ResponsiveProp<nowrap \| wrap \| wrap-reverse>` | No | `-` | - |
| `font` | `ResponsiveProp<FontFamily \| inherit>` | No | `-` | - |
| `fontFamily` | `ResponsiveProp<FontFamily \| inherit>` | No | `-` | - |
| `fontSize` | `ResponsiveProp<FontSize \| inherit>` | No | `-` | - |
| `fontWeight` | `ResponsiveProp<FontWeight \| inherit>` | No | `-` | - |
| `gap` | `ResponsiveProp<Space>` | No | `-` | - |
| `grid` | `ResponsiveProp<Grid>` | No | `-` | - |
| `gridArea` | `ResponsiveProp<GridArea>` | No | `-` | - |
| `gridAutoColumns` | `ResponsiveProp<GridAutoColumns<string \| number>>` | No | `-` | - |
| `gridAutoFlow` | `ResponsiveProp<GridAutoFlow>` | No | `-` | - |
| `gridAutoRows` | `ResponsiveProp<GridAutoRows<string \| number>>` | No | `-` | - |
| `gridColumn` | `ResponsiveProp<GridColumn>` | No | `-` | - |
| `gridColumnEnd` | `ResponsiveProp<GridColumnEnd>` | No | `-` | - |
| `gridColumnStart` | `ResponsiveProp<GridColumnStart>` | No | `-` | - |
| `gridRow` | `ResponsiveProp<GridRow>` | No | `-` | - |
| `gridRowEnd` | `ResponsiveProp<GridRowEnd>` | No | `-` | - |
| `gridRowStart` | `ResponsiveProp<GridRowStart>` | No | `-` | - |
| `gridTemplate` | `ResponsiveProp<GridTemplate>` | No | `-` | - |
| `gridTemplateAreas` | `ResponsiveProp<GridTemplateAreas>` | No | `-` | - |
| `gridTemplateColumns` | `ResponsiveProp<GridTemplateColumns<string \| number>>` | No | `-` | - |
| `gridTemplateRows` | `ResponsiveProp<GridTemplateRows<string \| number>>` | No | `-` | - |
| `height` | `ResponsiveProp<Height<string \| number>>` | No | `-` | - |
| `hideControls` | `boolean` | No | `-` | Hides the Calendar next and previous month arrows, but does not prevent navigating to the next or previous months via keyboard. This probably only makes sense to be used when minDate and maxDate are set to the first and last days of the same month. |
| `highlightedDateAccessibilityHint` | `string` | No | `'Highlighted'` | Accessibility hint announced for highlighted dates. Applied to all highlighted dates. |
| `highlightedDates` | `(Date \| [Date, Date])[]` | No | `-` | Array of highlighted dates, and date tuples for date ranges. A number is created for every individual date within a tuple range, so do not abuse this with massive ranges. |
| `justifyContent` | `ResponsiveProp<left \| right \| center \| normal \| start \| end \| flex-start \| flex-end \| stretch \| space-between \| space-around \| space-evenly>` | No | `-` | - |
| `key` | `Key \| null` | No | `-` | - |
| `left` | `ResponsiveProp<Left<string \| number>>` | No | `-` | - |
| `lineHeight` | `ResponsiveProp<LineHeight \| inherit>` | No | `-` | - |
| `margin` | `ResponsiveProp<0 \| -5 \| -10 \| -0.25 \| -0.5 \| -0.75 \| -1 \| -1.5 \| -2 \| -3 \| -4 \| -6 \| -7 \| -8 \| -9>` | No | `-` | - |
| `marginBottom` | `ResponsiveProp<0 \| -5 \| -10 \| -0.25 \| -0.5 \| -0.75 \| -1 \| -1.5 \| -2 \| -3 \| -4 \| -6 \| -7 \| -8 \| -9>` | No | `-` | - |
| `marginEnd` | `ResponsiveProp<0 \| -5 \| -10 \| -0.25 \| -0.5 \| -0.75 \| -1 \| -1.5 \| -2 \| -3 \| -4 \| -6 \| -7 \| -8 \| -9>` | No | `-` | - |
| `marginStart` | `ResponsiveProp<0 \| -5 \| -10 \| -0.25 \| -0.5 \| -0.75 \| -1 \| -1.5 \| -2 \| -3 \| -4 \| -6 \| -7 \| -8 \| -9>` | No | `-` | - |
| `marginTop` | `ResponsiveProp<0 \| -5 \| -10 \| -0.25 \| -0.5 \| -0.75 \| -1 \| -1.5 \| -2 \| -3 \| -4 \| -6 \| -7 \| -8 \| -9>` | No | `-` | - |
| `marginX` | `ResponsiveProp<0 \| -5 \| -10 \| -0.25 \| -0.5 \| -0.75 \| -1 \| -1.5 \| -2 \| -3 \| -4 \| -6 \| -7 \| -8 \| -9>` | No | `-` | - |
| `marginY` | `ResponsiveProp<0 \| -5 \| -10 \| -0.25 \| -0.5 \| -0.75 \| -1 \| -1.5 \| -2 \| -3 \| -4 \| -6 \| -7 \| -8 \| -9>` | No | `-` | - |
| `maxDate` | `Date` | No | `-` | Maximum date allowed to be selected, inclusive. Dates after the maxDate are disabled. All navigation to months after the maxDate is disabled. |
| `maxHeight` | `ResponsiveProp<MaxHeight<string \| number>>` | No | `-` | - |
| `maxWidth` | `ResponsiveProp<MaxWidth<string \| number>>` | No | `-` | - |
| `minDate` | `Date` | No | `-` | Minimum date allowed to be selected, inclusive. Dates before the minDate are disabled. All navigation to months before the minDate is disabled. |
| `minHeight` | `ResponsiveProp<MinHeight<string \| number>>` | No | `-` | - |
| `minWidth` | `ResponsiveProp<MinWidth<string \| number>>` | No | `-` | - |
| `nextArrowAccessibilityLabel` | `string` | No | `'Go to next month'` | Accessibility label describing the Calendar next month arrow. |
| `onChange` | `FormEventHandler<HTMLDivElement>` | No | `-` | - |
| `onPressDate` | `((date: Date) => void)` | No | `-` | Callback function fired when pressing a Calendar date. |
| `opacity` | `ResponsiveProp<Opacity>` | No | `-` | - |
| `overflow` | `ResponsiveProp<hidden \| auto \| visible \| clip \| scroll>` | No | `-` | - |
| `padding` | `ResponsiveProp<Space>` | No | `-` | - |
| `paddingBottom` | `ResponsiveProp<Space>` | No | `-` | - |
| `paddingEnd` | `ResponsiveProp<Space>` | No | `-` | - |
| `paddingStart` | `ResponsiveProp<Space>` | No | `-` | - |
| `paddingTop` | `ResponsiveProp<Space>` | No | `-` | - |
| `paddingX` | `ResponsiveProp<Space>` | No | `-` | - |
| `paddingY` | `ResponsiveProp<Space>` | No | `-` | - |
| `pin` | `PinningDirection` | No | `-` | Direction in which to absolutely pin the box. |
| `position` | `ResponsiveProp<fixed \| static \| relative \| absolute \| sticky>` | No | `-` | - |
| `previousArrowAccessibilityLabel` | `string` | No | `'Go to previous month'` | Accessibility label describing the Calendar previous month arrow. |
| `ref` | `((instance: HTMLElement \| null) => void) \| RefObject<HTMLElement> \| null` | No | `-` | - |
| `right` | `ResponsiveProp<Right<string \| number>>` | No | `-` | - |
| `rowGap` | `ResponsiveProp<Space>` | No | `-` | - |
| `seedDate` | `Date` | No | `-` | Date used to generate the Calendar month when there is no value for the selectedDate prop, defaults to today. |
| `selectedDate` | `Date \| null` | No | `-` | Currently selected Calendar date. Date used to generate the Calendar month. Will be rendered with active styles. |
| `style` | `CSSProperties` | No | `-` | - |
| `styles` | `{ readonly root?: CSSProperties; readonly header?: CSSProperties \| undefined; readonly title?: CSSProperties \| undefined; readonly navigation?: CSSProperties \| undefined; readonly content?: CSSProperties \| undefined; readonly day?: CSSProperties \| undefined; } \| undefined` | No | `-` | - |
| `testID` | `string` | No | `-` | Used to locate this element in unit and end-to-end tests. Under the hood, testID translates to data-testid on Web. On Mobile, testID stays the same - testID |
| `textAlign` | `ResponsiveProp<center \| start \| end \| justify>` | No | `-` | - |
| `textDecoration` | `ResponsiveProp<none \| underline \| overline \| line-through \| underline overline \| underline double>` | No | `-` | - |
| `textTransform` | `ResponsiveProp<capitalize \| lowercase \| none \| uppercase>` | No | `-` | - |
| `top` | `ResponsiveProp<Top<string \| number>>` | No | `-` | - |
| `transform` | `ResponsiveProp<Transform>` | No | `-` | - |
| `userSelect` | `ResponsiveProp<text \| none \| auto \| all>` | No | `-` | - |
| `visibility` | `ResponsiveProp<hidden \| visible>` | No | `-` | - |
| `width` | `ResponsiveProp<Width<string \| number>>` | No | `-` | - |
| `zIndex` | `ResponsiveProp<ZIndex>` | No | `-` | - |


## Styles

| Selector | Static class name | Description |
| --- | --- | --- |
| `root` | `cds-Calendar` | Root element |
| `header` | `cds-Calendar-header` | Header section |
| `title` | `cds-Calendar-title` | Month and year title text element |
| `navigation` | `cds-Calendar-navigation` | Navigation controls element |
| `content` | `cds-Calendar-content` | Main content area |
| `day` | `cds-Calendar-day` | Individual date cell in a calendar grid |