# Calendar A calendar for selecting a single date, several dates, or a range of dates. ```twig ``` ## Installation > [!NOTE] > Available since UX Toolkit 3.5. ```shell php bin/console ux:install calendar --kit shadcn ``` ## Usage ```twig ``` Dates are exchanged as `Y-m-d` strings. When `name` is set, the selection is mirrored into hidden inputs (`name`, `name[]` in `multiple` mode, `name[from]` and `name[to]` in `range` mode) so the calendar can be submitted with a form. Selecting a date also dispatches a `calendar:select` event, and navigating to another month dispatches a `calendar:month-change` event; both bubble, so an ancestor element can listen for them. This is the way to react to the selection without reading the hidden inputs. ## Examples ### Basic A calendar with no initial selection. Use `class="rounded-lg border"` to frame it. ```twig ``` ### Range Calendar Use `mode="range"` to select a period. The first entry of `selected` is the start of the range, the second one its end. ```twig ``` ### Multiple Use `mode="multiple"` to select any number of individual dates. ```twig ``` ### Month and Year Selector Use `captionLayout="dropdown"` to replace the caption with month and year dropdowns. Their range is bounded by `startMonth` and `endMonth`. ```twig ``` ### Presets Anything placed inside the calendar is rendered below the grid, and is within reach of the `calendar` controller: a button carrying `data-action="click->calendar#selectDate"` and a `data-calendar-date-param` selects that date and jumps to its month. ```twig
{% for preset in [{label: 'Today', days: 0}, {label: 'Tomorrow', days: 1}, {label: 'In 3 days', days: 3}, {label: 'In a week', days: 7}, {label: 'In 2 weeks', days: 14}] %} {{ preset.label }} {% endfor %}
``` ### Date and Time Picker ```twig Start Time End Time ``` ### Booked Dates Every entry of `modifiers` is rendered as a `data-` attribute on the matching days, which is enough to style them with an arbitrary utility. ```twig {% set bookedDates = (0..14)|map(offset => '2026-02-12'|date_modify('+' ~ offset ~ ' days')|date('Y-m-d')) %} ``` ### Custom Cell Size Cells are sized with the `--cell-size` CSS variable, which can be overridden per breakpoint. ```twig ``` ### Week Numbers Use `showWeekNumber` to prepend a column with the ISO week number. ```twig ``` ### API The calendar dispatches a `calendar:select` event on every selection change, with `selected` (the dates, as `Y-m-d` strings) and `mode` in its detail, and a `calendar:month-change` event on every navigation, with `month` in its detail. Both events bubble. The `calendar-display` controller shipped with this recipe listens to `calendar:select` and mirrors the selection into a visible read-only field. ```twig
Selected dates
``` ### RTL To enable RTL support, set the `dir="rtl"` attribute on the root element. Pair it with `locale` so the month, weekday and day labels are formatted for that language, and with `weekStartsOn` so the week starts on the expected day. The `-u-nu-` Unicode extension pins the numbering system the digits are drawn from. Worth setting explicitly for languages that have more than one in use: a bare `ar` resolves to Arabic-Indic digits or Latin ones depending on the ICU version, and the server and the browser do not necessarily ship the same one. ```twig
{# Arabic #} {# Hebrew #}
``` ## Accessibility - The root element renders `role="group"` with an `aria-label` taken from the `label` prop (`Calendar` by default), and each displayed month is a `` whose `aria-label` is the localized month and year. - Weekday headers are `
` showing a narrow abbreviation, with the full weekday name exposed through `aria-label`. Every day cell carries `aria-selected`, and its button has an `aria-label` holding the full localized date, so a screen reader announces the whole date rather than a bare number. - Only one day button per calendar is in the tab order (roving `tabindex`): the selected day, today, or the first of the displayed month. From there, arrow keys move by one day and one week, `Home` and `End` jump to the edges of the week, `PageUp` and `PageDown` move by one month, and left and right are swapped in RTL. Moving outside the displayed month navigates to it. - The previous and next month buttons are icon-only with a visually hidden label, hardcoded in the template, so translate them there. They use `aria-disabled` rather than `disabled` at the navigation bounds, so they stay reachable by keyboard and simply do nothing. - With `captionLayout="dropdown"`, the month and year `