ChronousDocumentation

Integrations

shadcn/ui

An editable day, week, month and agenda calendar for shadcn/ui, installed with one CLI command.

A calendar from the shadcn registry

ChronousCalendar is a shadcn/ui registry item: one editable file in your components/ui, built on @midstem/chronous-react, your Button and your theme tokens. It brings day, week, month and agenda views, recurring events, time zones and locales, and it is yours to change after the CLI copies it in.

Live preview

This is the registry file running inside a real shadcn/ui project. Switch views, step through weeks, change the locale or time zone, and open the Code tab for the exact source the CLI installs.

Loading the shadcn/ui playground…

Prefer more room? Open the playground in a new tab or pick shadcn/ui on the Playground page.

Installation

Run the shadcn CLI from the root of an app that already has a components.json:

Terminal
npx shadcn@latest add https://midstem.github.io/chronous/r/chronous-calendar.json

The CLI then:

  • writes components/ui/chronous-calendar.tsx, rewriting its imports to your aliases;
  • installs @midstem/chronous-react, temporal-polyfill, class-variance-authority and lucide-react;
  • adds the shadcn button if your app does not have it yet.

To install by name instead of URL, register the namespace in components.json:

components.json
{
  "registries": {
    "@chronous": "https://midstem.github.io/chronous/r/{name}.json"
  }
}
Terminal
npx shadcn@latest add @chronous/chronous-calendar

Usage

Events use the same EventInput shape as the rest of Chronous, with a title and an optional color in data. Recurring series expand only for the period on screen.

schedule.tsx
import {
  ChronousCalendar,
  type ChronousCalendarEvent
} from '@/components/ui/chronous-calendar'

const events: ChronousCalendarEvent[] = [
  {
    id: 'standup',
    start: '2026-03-16T09:30',
    duration: 'PT15M',
    recurrence: { rule: 'FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR' },
    data: { title: 'Daily standup', color: 'chart-1' }
  },
  {
    id: 'offsite',
    start: '2026-03-19',
    duration: 'P2D',
    allDay: true,
    data: { title: 'Team offsite', color: 'chart-4' }
  }
]

export function Schedule() {
  return (
    <ChronousCalendar
      events={events}
      defaultView="week"
      timeZone="Europe/Kyiv"
      locale="en-GB"
    />
  )
}

Props

PropTypeDefaultDescription
eventsChronousCalendarEvent[][]Events and recurring series. data.title is required, data.color picks a chart token.
defaultView'day' | 'week' | 'month' | 'agenda''week'The view the calendar opens on. Read once, on mount.
defaultDatestringtodayThe ISO date the calendar opens on. Pass a stable value when rendering on the server.
timeZonestringbrowser zoneThe IANA zone every date, event and the now marker are computed in. The server renders UTC until hydration.
localestring'en-US'Formats month titles, weekdays and event times.
scrollToHournumber | null8Where the day and week grid opens. null keeps it at midnight.
classNamestring—Merged with cn onto the outer section, along with every other section prop.

Make it yours

The component lives in your repository, so restyle it the way you restyle any shadcn component. Event colors come from the calendarEventVariants recipe, exported next to the component:

ColorTypeDefaultDescription
chart-1 … chart-5ChronousCalendarEventColor'chart-2'A soft fill, a tinted border and a solid leading edge, all from your theme’s chart tokens, so events follow light and dark mode.

Add a tone by adding a variant, then use its name as data.color after widening ChronousCalendarEventColor:

chronous-calendar.tsx
const calendarEventVariants = cva(
  'flex w-full min-w-0 overflow-hidden rounded-md border border-l-2 text-foreground',
  {
    variants: {
      color: {
        'chart-1': 'border-chart-1/25 border-l-chart-1 bg-chart-1/10',
        // …
        brand: 'border-primary/25 border-l-primary bg-primary/10'
      }
    }
  }
)

For the full walkthrough, the local registry build and the playground tests, see the registry guide on GitHub.