---
source_hash: "5b38d5e6"
title: "Calendar"
weight: 80
---

# Calendar

SmartCommon provides two calendar components. They share the same base but serve different needs.

| Component | Usage |
| --- | --- |
| `Calendar` | Date input in a form |
| `PlainCalendar` | Standalone calendar view, with ability to display events and select a range |

## Calendar

Monthly date picker with month-by-month navigation and year selector. It automatically integrates with a `<Form>` via `useField`.

```javascript
import { Calendar } from '@cap-rel/smartcommon';

<Calendar
  name="date_intervention"
  value={value}
  onChange={setValue}
  yearsInterval={[2020, 2035]}
  onMonthChange={(month) => console.log(month)}
  onYearChange={(year) => console.log(year)}
/>
```

### Main Props

| Prop | Type | Description |
| --- | --- | --- |
| `name` | string | Field name in the form |
| `value` | string | Selected date, in ISO format `YYYY-MM-DD` |
| `defaultValue` | string | Initial value in uncontrolled mode |
| `onChange` | function | Called on each selection |
| `yearsInterval` | array | Year selector bounds, default `[2000, 2030]` |
| `items` | array | Events to mark in the grid |
| `onMonthChange` | function | Called on each month change |
| `onYearChange` | function | Called on each year change |

### Value Format

> [!IMPORTANT]
> The value is an **ISO string** `"YYYY-MM-DD"`, or `null`. A native `Date` object is not accepted; convert it yourself.

```javascript
const iso = new Date().toISOString().slice(0, 10);
```

### Known Limitations
- Single date selection only, no range (use `PlainCalendar` with `interval`)
- No date disabling via prop (weekends, holidays, past dates)
- No time or minutes: this is a date picker only
- Display locale follows browser locale and is not configurable
- No native validation: validate on parent side, or in the form's `onPreSubmit`

## PlainCalendar

Standalone calendar view, outside of form context. It accepts range selection and display of dated items.

```javascript
import { PlainCalendar } from '@cap-rel/smartcommon';
import { useSmartcommonLabels } from 'src/hooks/useSmartcommonLabels';

const labels = useSmartcommonLabels();

<PlainCalendar
  value={value}
  onChange={setValue}
  interval
  items={events}
  labels={labels.PlainCalendar}
/>
```

| Prop | Type | Description |
| --- | --- | --- |
| `value` | string or array | Date, or pair of dates if `interval` |
| `onChange` | function | Called on each selection |
| `interval` | bool | Enable range selection, default `false` |
| `items` | array | Dated items to display in the grid |
| `yearsInterval` | array | Year selector bounds |
| `labels` | object | Interface labels |

### Labels and Translation

`PlainCalendar` is one of the components that embed their own labels, in English by default. Pass it the active language bundle instead of hardcoding texts:

```javascript
import { locales, useGlobalStates } from "@cap-rel/smartcommon";

export const useSmartcommonLabels = () => {
    const gst = useGlobalStates();
    const lang = gst.get("user.settings.lang") ?? gst.get("publicSettings.lang") ?? "en";
    return locales[lang] ?? locales.en;
};
```

> [!WARNING]
> Never hardcode `locales.fr` in a page: users of other languages would end up with a French calendar.

### Neighboring Days Behavior

Clicking on a day from the previous or next month, in the cells that complete the first and last week, moves the grid to that month **and** selects the day.

## See Also
- [SmartCommon](/front/smartcommon) - Component List
- [Components and Pages](/front/composants-et-pages) - Forms
- [Component Variants](/front/variants) - Customize Appearance
- [Translations](/front/traductions)