Calendar
Month-view calendar grid for date selection, with min/max constraints, keyboard navigation, and today highlighting.
<arc-calendar>Overview
Calendar renders a full month grid with day-of-week headers, previous/next month navigation, and selectable date cells. It is the building block for date pickers and scheduling interfaces. The selected date is stored as an ISO string (YYYY-MM-DD) in the value prop, and the visible month is controlled independently via month (0-based) and year, so you can navigate programmatically without changing the selection.
Days from the previous and next months fill the grid to maintain a consistent 6-row layout, but these "outside" days are displayed at reduced opacity. The current date receives an inset ring highlight (--border-bright), while the selected date gets a solid accent-primary background. Optional min and max ISO date strings constrain the selectable range; disabled dates are dimmed and non-interactive.
Arrow keys move a focus ring through the grid (including automatic month transitions at boundaries), and Enter or Space confirms the selection. The component fires arc-change when a date is selected and arc-month-change when the visible month changes, so you can lazy-load events or availability data for the new period.
Guidelines
When to use
- Set `min` and `max` to constrain the selectable range when your use case has date boundaries
- Use `arc-month-change` to lazy-load events or availability data when the user changes months
- Pair Calendar with a text input or DatePicker wrapper for combined typed and visual date entry
- Pre-set `month` and `year` to the month containing the initial `value` so the selection is visible on load
- Provide sufficient container width (280px minimum) so the grid cells are easy to click
When not to use
- Do not use Calendar for time selection; it handles dates only
- Do not set `min` greater than `max`; the component will disable all days
- Do not use Calendar for date range selection (two dates); it supports single date selection only
- Do not override the monospace font on day cells; it keeps the columns aligned
- Avoid placing Calendar in extremely narrow containers below 280px; the grid cells become too small for touch targets
Features
- Standard 7-column month grid with Sun-Sat headers in monospace uppercase
- Previous and next month navigation buttons in the header
- Today highlighting with an inset border ring for orientation
- Selected date highlighted with solid accent-primary background and bold weight
- Min/max date constraints via ISO date strings that disable out-of-range days
- Arrow key navigation through the grid with automatic month transitions at boundaries
- Outside-month day cells shown at 30% opacity to fill the 6-row grid consistently
- Two events: `arc-change` on date selection and `arc-month-change` on month/year changes
Preview
Usage
This component requires JavaScript. No pure HTML/CSS version is available. Use the Web Component directly or a framework wrapper.
<arc-calendar></arc-calendar>import { Calendar } from '@arclux/arc-ui-react';
export default function Example() {
return (
<Calendar />
);
}<script setup>
import { Calendar } from '@arclux/arc-ui-vue';
</script>
<template>
<Calendar />
</template><script>
import { Calendar } from '@arclux/arc-ui-svelte';
</script>
<Calendar />import { Component } from '@angular/core';
import { Calendar } from '@arclux/arc-ui-angular';
@Component({
imports: [Calendar],
template: `
<arc-calendar></arc-calendar>
`,
})
export class MyComponent {}import { Calendar } from '@arclux/arc-ui-solid';
export default function Example() {
return (
<Calendar />
);
}import { Calendar } from '@arclux/arc-ui-preact';
export default function Example() {
return (
<Calendar />
);
}API
localestring''- BCP 47 tag used for month and weekday names. Defaults to the document's
lang, then the browser's language. valuestring''- The selected date as an ISO string (YYYY-MM-DD). Empty string means no date is selected.
minstring''- Minimum selectable date as an ISO string. Days before this date are disabled.
maxstring''- Maximum selectable date as an ISO string. Days after this date are disabled.
monthnumber- The currently displayed month (0-based, 0=January). Defaults to the current month. Clamped to 0-11: an out-of-range month reached
new Date(year, month), which silently rolls into another year. yearnumber- The currently displayed year. Defaults to the current year.
firstDayOfWeek0|1|2|3|4|5|6|70- Which day the week starts on, 1 = Monday … 7 = Sunday. 0 (the default) follows the locale's own convention. An unrecognised value falls back to 0 rather than reaching weekdayOffset() and reordering the week arbitrarily.
Events
arc-month-changedetail:{ month: number, year: number }- Fired when the visible month or year changes via the navigation buttons.
arc-change- Fired when a date is selected.
event.detail.valuecontains the ISO date string (YYYY-MM-DD).