---
url: https://ambiki.github.io/impulse_view_components/components/date-calendar.md
---
# Date calendar

A grid of a month's days for choosing one. It renders no input or popover of its own: show it inline, or in a
[popover](./popover.md), and listen for the day the user commits. In a form, use a native `<input type="date">`
instead.

## Usage

```erb
<%= render(Impulse::DateCalendarComponent.new(value: Date.new(2026, 11, 18))) %>
```

The calendar shows the month of its value, with previous and next month buttons. Clicking a day, or pressing Enter or
Space on it, commits it: the day becomes the value and the calendar emits `awc-date-calendar:commit`. Committing the
day already selected emits nothing.

Pressing the heading, which names the month, shows the months of its year in the same box, and pressing it again shows
the years of its decade. Choosing a year shows its months, and choosing a month shows its days. Neither commits
anything.

## Arguments

### Keyword arguments

| Name                  | Default                 | Description                                                                                                                       |
| ------                | -------                 | -------------                                                                                                                     |
| value                 | `nil`                   | The selected day: a `Date`, a `Time` or `ActiveSupport::TimeWithZone`, or an ISO 8601 string, `YYYY-MM-DD` or a time. Times are read in the time zone. |
| min                   | `nil`                   | The earliest day the user can commit, given as `value` is.                                                                         |
| max                   | `nil`                   | The latest day the user can commit, given as `value` is.                                                                           |
| disabled_days_of_week | `[]`                    | The days of the week the user can't commit, as names (`%i[saturday sunday]`) or numbers (`0` is Sunday).                          |
| first_day_of_week     | `Date.beginning_of_week` | The day each week starts on, as a name or a number.                                                                              |
| time_zone             | see below               | The time zone that decides which day is today, and which day a time falls on.                                                    |
| disabled              | `false`                 | Whether the calendar is disabled: nothing in it can be focused or pressed. It still shows its value.                             |

Any other keyword arguments, such as `class` or `data`, are passed to the `<awc-date-calendar>` element as HTML
attributes. Render the calendar with the component: the element relies on the month and the settings it renders.

The time zone is `time_zone:` when given, else the zone of an `ActiveSupport::TimeWithZone` value, else `Time.zone`.
The calendar follows the app's settings, not the browser's: its time zone, its first day of the week, and its
translations.

## Examples

### Limiting the days

Days before `min`, after `max`, or on a disabled day of the week can be reached by keyboard but not committed. The
calendar doesn't page past the months holding `min` and `max`.

```erb
<%= render(Impulse::DateCalendarComponent.new(
  value: appointment.date,
  min: Date.current,
  max: 3.months.from_now,
  disabled_days_of_week: %i[saturday sunday]
)) %>
```

A value outside them is still shown selected.

### In a popover

Focus the selected day when the popover opens, so that the keys move through the grid straight away, as they do in a
date picker dialog. Close the popover when the user commits a day, and take the calendar back to the selected day when
the popover closes, so that it reopens there rather than on a month the user paged to.

```erb
<%= render(Impulse::PopoverComponent.new(title: "Choose a date", data: { action: "awc-date-calendar:commit->awc-popover#requestHide" })) do |c| %>
  <% c.with_trigger(class: "btn btn-outline-secondary") { l(@date, format: :long) } %>
  <% c.with_header(visually_hide_title: true, hide_close_button: true) %>
  <% c.with_body do %>
    <%= render(Impulse::DateCalendarComponent.new(value: @date)) %>
  <% end %>
<% end %>
```

```js
const calendar = popover.querySelector('awc-date-calendar');
popover.addEventListener('awc-popover:shown', () => calendar.focus());
popover.addEventListener('awc-popover:hidden', () => calendar.resetView());
```

### Translations

Month and weekday names come from Rails' `date.month_names`, `date.abbr_month_names`, `date.day_names` and
`date.abbr_day_names`. The button labels and the patterns are shared by the calendars:

```yaml
en:
  impulse:
    calendar:
      previous_month: Previous month
      next_month: Next month
      previous_year: Previous year
      next_year: Next year
      previous_decade: Previous decade
      next_decade: Next decade
      choose_month: Choose a month # Describes the heading's button on the days.
      choose_year: Choose a year # Describes the heading's button on the months.
      formats:
        month_heading: "%B %Y" # Names the displayed month, above the grid.
        day: "%A, %B %-d, %Y" # Each day's accessible name.
        month: "%B %Y" # Each month's accessible name.
        decade: "%{start} – %{end}" # Names the displayed decade, above the years.
```

Add them for each other locale. The `strftime` patterns can use `%A %a %B %b %d %-d %e %m %Y` and `%%`.

## Accessibility

The calendar follows the grid of the
[APG date picker dialog example](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/).
The grid is one tab stop, named by the month, and each day is a button named by its full date. Turning the page
announces the new month.

The heading is a button named by its month and described as "Choose a month". Pressing it moves focus to the month
shown, in a grid named by its year; that heading, described as "Choose a year", moves on to the years, named by their
decade. Choosing a year moves focus to the same month in it, and choosing a month to the same day, or the nearest one
`min` and `max` allow. The decade heading can't be pressed: choose the year shown to go back. On the months and years,
the keys are the [month calendar](./month-calendar.md#accessibility)'s and the
[year calendar](./year-calendar.md#accessibility)'s, and Enter or Space chooses.

| Key                              | Moves to                             |
| ------                           | ------------                         |
| Left Arrow, Right Arrow          | The day before or after              |
| Up Arrow, Down Arrow             | The same day of the week before or after |
| Home, End                        | The start or end of the week         |
| Page Up, Page Down               | The same day of the month before or after |
| Shift + Page Up, Shift + Page Down | The same day of the year before or after |
| Enter, Space                     | Commits the day                      |

Moving past the edge of the month turns the page. The calendar keeps its size on the months and years.

## Imports

::: code-group

```js
import '@ambiki/impulse-view-components/date-calendar';
```

```scss
@import '@ambiki/impulse-view-components/date-calendar';
```

:::

The styles need Bootstrap's Sass and the base styles loaded first. See [Import the styles](/introduction/getting-started#import-the-styles).

## JS API

[Read here](../js-api/date-calendar.md).
