Calendar

A month grid built on the client: navigation, single or range selection, and keyboard support.

Installation

Shadwire follows shadcn/ui's open code model: the component's source is copied into your application and becomes yours. Install it with the CLI:

shadwire add calendar --yes

The calendar registry item installs these files:

app/components/ui_component.rb
app/components/ui/calendar_component.rb
app/helpers/ui/calendar_helper.rb
app/javascript/controllers/ui_calendar_controller.js
vendor/shadwire/shadwire.css

This component uses Stimulus, so the application needs importmap-rails and stimulus-rails with automatic controller loading.

Haven't installed the CLI yet? gem install shadwire, then shadwire init.

Usage

The server only renders the frame; the ui-calendar controller builds the days in the browser, so changing month does not make a request. The chosen date goes into an input[type=hidden], so inside a form_with the calendar is submitted like any other field. For a field that opens the calendar in a popover, see Date Picker.

<%= ui_calendar(selected: Date.current, name: "date", class: "border") %>

<%# Range: two dates, two inputs, two months. %>
<%= ui_calendar(
      mode: :range,
      selected: Date.current..(Date.current + 7),
      number_of_months: 2,
      name: "trip[starts_on]",

<%= ui_calendar(selected: Date.current, name: "date", class: "border") %>

<%# Range: two dates, two inputs, two months. %>
<%= ui_calendar(
      mode: :range,
      selected: Date.current..(Date.current + 7),
      number_of_months: 2,
      name: "trip[starts_on]",
      end_name: "trip[ends_on]"
    ) %>

Examples

Default

The current month with today selected. Arrows walk the days, Home/End jump to the ends of the week, and PageUp/PageDown change month.

<%# Inline, the calendar draws its own frame; inside a popover the popover
    plays that part, so the border is left to whoever uses it. %>
<%= ui_calendar(selected: Date.today, name: "date", class: "border") %>

Range

mode: :range records two dates; hovering after the first click previews the range. number_of_months: 2 shows two months side by side.

<%= ui_calendar(
      mode: :range,
      selected: Date.current..(Date.current + 12),
      number_of_months: 2,
      name: "trip[starts_on]",
      end_name: "trip[ends_on]",
      class: "border"
    ) %>

Caption with selects

caption_layout: :dropdown replaces the month name with month and year selects, which makes a distant year quicker to reach.

<%# `min:`/`max:` disable the days outside the range and bound the year select. %>
<%= ui_calendar(
      caption_layout: :dropdown,
      name: "born_on",
      min: Date.new(1930, 1, 1),
      max: Date.current,
      class: "border"
    ) %>

API reference

Dates accept a Date or an ISO YYYY-MM-DD. Like every component, it also accepts class / class_name and **attrs.

Argument	Default	Description
`mode`	`:single`	`:range` selects a range; the second click closes the far end.
`selected`	—	The chosen date. With `:range` it takes a range (`Date..Date`).
`from`, `to`	—	The ends of the range, when you would rather pass them separately.
`name`, `end_name`	—	The hidden inputs. `name` is the date (or the start); `end_name` the end.
`month`	the selection, otherwise today	The first visible month.
`min`, `max`	—	Disable the days outside the span, and bound the year select.
`number_of_months`	`1`	Consecutive months side by side. `2` is the usual pair for ranges.
`caption_layout`	`:label`	`:dropdown` swaps the month name for month and year selects (single month only).
`year_range`	−100…+10 years	The years in the select. `min:`/`max:` win when given.
`dir`	—	`:rtl` mirrors the grid, the navigation arrows and the ←/→ keys.
`week_start`	`0`	The first day of the week: `0` Sunday, `1` Monday.
`month_names`, `day_names`	From I18n	Caption and header labels. By default Rails' `date.month_names` and `date.abbr_day_names`, in the app's locale; pass arrays to override them.

Events: ui-calendar:change on each selection and ui-calendar:connect when the calendar builds, both carrying detail: { date, from, to }. The other way round, ui-calendar#setDate moves the calendar to a date coming from elsewhere.