Calendar
⋯
Calendar renders the Figma Calendar component: a header with the date icon, title, week badge, navigation, and view menu, followed by a Month, Week, or Day view of the events you pass in. Below 640 px of container width it switches to the Figma Mobile layouts.
import { Calendar, type CalendarEvent } from "@nesra/ui/calendar";
const events: CalendarEvent[] = [ { id: "demo", title: "Product demo", start: "2027-01-08T13:30", end: "2027-01-08T15:30" },];
export function TeamCalendar() { return <Calendar events={events} timeZone="Asia/Jakarta" />;}The root import @nesra/ui also exports Calendar and its types.
Composition
Section titled “Composition”Calendar├── Header: date icon, title, Week badge, range text│ ├── Previous · Today · Next│ ├── View menu (Day view, Week view, Month view)│ └── actions (your content)├── Month view grid (desktop cells show a “+” button with onAddEvent)└── Week/Day time grid ├── All-day lane (when the visible days have all-day events) └── Day view side panel (Desktop layout) ├── Mini calendar (DatePicker, calendar presentation) └── Event details: title, renderEventActions, date, time, renderEventDetailsThe header, views, cells, and events are rendered from props. Calendar has no public parts.
Examples
Section titled “Examples”Month view
Section titled “Month view”import { Button } from "@nesra/ui/button";import { Calendar, type CalendarEvent } from "@nesra/ui/calendar";import { Plus } from "lucide-react";
const events: CalendarEvent[] = [ { id: "1", title: "Monday standup", start: "2027-01-04T09:00", end: "2027-01-04T09:30" }, { id: "2", title: "Content planning", start: "2027-01-04T11:00", end: "2027-01-04T12:00", color: "blue", }, { id: "3", title: "Catch up w/ Alex", start: "2027-01-05T14:30", end: "2027-01-05T16:00", color: "purple", }, { id: "4", title: "Lunch with Olivia", start: "2027-01-07T12:00", end: "2027-01-07T13:00", color: "green", dot: true, }, { id: "5", title: "Friday standup", start: "2027-01-08T09:00", end: "2027-01-08T09:30" }, { id: "6", title: "Olivia x Riley", start: "2027-01-08T10:00", end: "2027-01-08T11:00", color: "brand", }, { id: "7", title: "Product demo", start: "2027-01-08T13:30", end: "2027-01-08T15:30", color: "indigo", }, { id: "8", title: "Team dinner", start: "2027-01-08T18:00", end: "2027-01-08T20:00", color: "pink", }, { id: "9", title: "House inspection", start: "2027-01-09T11:00", end: "2027-01-09T12:00", color: "orange", dot: true, }, { id: "10", title: "Accountant", start: "2027-01-22T13:45", end: "2027-01-22T14:30", color: "yellow", },];
export function CalendarMonthExample() { return ( <Calendar className="w-full" defaultDate="2027-01-08" events={events} now={new Date("2027-01-08T07:20:00Z")} timeZone="Asia/Jakarta" weekStartsOn={1} actions={ <Button size="sm" startIcon={<Plus />}> Add event </Button> } /> );}A month cell shows up to three events. Further events collapse into an “N more…” button that opens
the Day view for that date. Days outside the month use Surface/card-bg-gray, and their dates use
Text/text-support.
Week view
Section titled “Week view”import { Calendar, type CalendarEvent } from "@nesra/ui/calendar";
const events: CalendarEvent[] = [ { id: "1", title: "Monday standup", start: "2027-01-04T09:00", end: "2027-01-04T09:30" }, { id: "2", title: "Deep work", start: "2027-01-06T09:00", end: "2027-01-06T10:30", color: "blue", }, { id: "3", title: "Design sync", start: "2027-01-06T10:00", end: "2027-01-06T11:00", color: "indigo", }, { id: "4", title: "Lunch with Olivia", start: "2027-01-07T12:00", end: "2027-01-07T13:00", color: "green", dot: true, }, { id: "5", title: "Product demo", start: "2027-01-08T13:30", end: "2027-01-08T15:30", color: "indigo", }, { id: "6", title: "Meetup event", start: "2027-01-06T15:00", end: "2027-01-06T17:00", color: "yellow", },];
export function CalendarWeekExample() { return ( <Calendar className="w-full" defaultDate="2027-01-08" defaultView="week" events={events} now={new Date("2027-01-08T07:20:00Z")} timeZone="Asia/Jakarta" weekStartsOn={1} /> );}Week and Day views draw a 24-hour grid, 96 px per hour, that scrolls inside a 672 px area. The grid opens at the earliest event of the visible range, or at 8 AM when that is earlier. Events that overlap in time share the column side by side. An event that crosses midnight is drawn on each day it covers. The current-time marker appears when today is visible.
Day view side panel
Section titled “Day view side panel”import { Avatar } from "@nesra/ui/avatar";import { Button } from "@nesra/ui/button";import { Calendar, type CalendarEvent } from "@nesra/ui/calendar";import { Bell, Copy, Pencil, Trash2 } from "lucide-react";
const events: CalendarEvent[] = [ { id: "1", title: "Friday standup", start: "2027-01-08T09:00", end: "2027-01-08T09:30" }, { id: "2", title: "Olivia x Riley", start: "2027-01-08T10:00", end: "2027-01-08T11:00", color: "brand", }, { id: "3", title: "Product demo", start: "2027-01-08T13:30", end: "2027-01-08T15:30", color: "indigo", },];
const guests = ["Sienna Hewitt", "Riley Chen", "Olivia Rahman"];
export function CalendarDayPanelExample() { return ( <Calendar className="w-full" defaultDate="2027-01-08" defaultView="day" events={events} now={new Date("2027-01-08T07:20:00Z")} timeZone="Asia/Jakarta" renderEventActions={(event) => ( <> <Button aria-label={`Duplicate ${event.title}`} size="icon-sm" variant="ghost"> <Copy aria-hidden="true" className="text-nesra-icon-neutral" /> </Button> <Button aria-label={`Delete ${event.title}`} size="icon-sm" variant="ghost"> <Trash2 aria-hidden="true" className="text-nesra-icon-neutral" /> </Button> <Button aria-label={`Edit ${event.title}`} size="icon-sm" variant="ghost"> <Pencil aria-hidden="true" className="text-nesra-icon-neutral" /> </Button> </> )} renderEventDetails={() => ( <> <p className="-mt-nesra-spacing-md flex items-center gap-nesra-spacing-sm type-nesra-body-small-regular text-nesra-text-support"> <Bell aria-hidden="true" className="size-nesra-unit-7 text-nesra-icon-muted" /> 10 min before </p> <div className="flex flex-col gap-nesra-spacing-lg"> <Avatar.Group label="Guests"> {guests.map((name) => ( <Avatar key={name} name={name} size="md" /> ))} </Avatar.Group> <p className="type-nesra-body-small-semibold text-nesra-text-headline"> 3 guests{" "} <span className="type-nesra-body-small-regular text-nesra-text-support"> · 2 yes · 1 awaiting </span> </p> </div> <div className="flex flex-col gap-nesra-spacing-md"> <p className="type-nesra-body-small-semibold text-nesra-text-headline"> About this event </p> <p className="type-nesra-body-small-regular text-nesra-text-support"> Product demo for the new dashboard, followed by questions from the team. </p> </div> </> )} /> );}In the Desktop layout, 640 px of container width and wider, the Day view shows a 328 px side panel. Its top half is the Date Picker calendar, which selects the Calendar date. The bottom half describes one event of that date:
- The last event the user clicked or activated, in any view, when it falls on that date.
- Otherwise, on today, the first timed event that has not ended.
- Otherwise, the first event of the date. A date without events shows “No events”.
Calendar renders the event title, its date, and its time range, or “All day”.
renderEventActions adds content beside the title, and renderEventDetails adds content below the
time. Reminders, guests, descriptions, and the actions themselves belong to the application. Set
sidePanel={false} to hide the panel.
All-day events
Section titled “All-day events”import { Calendar, type CalendarEvent } from "@nesra/ui/calendar";
const events: CalendarEvent[] = [ { id: "offsite", title: "Team offsite", start: "2027-01-06", end: "2027-01-07", allDay: true, color: "green", }, { id: "holiday", title: "Public holiday", start: "2027-01-08", end: "2027-01-08", allDay: true }, { id: "demo", title: "Product demo", start: "2027-01-08T13:30", end: "2027-01-08T15:30", color: "indigo", },];
export function CalendarAllDayExample() { return ( <Calendar className="w-full" defaultDate="2027-01-08" defaultView="week" events={events} now={new Date("2027-01-08T07:20:00Z")} sidePanel={false} timeZone="Asia/Jakarta" weekStartsOn={1} /> );}Set allDay: true and give start and end as YYYY-MM-DD dates. end is the last day and is
inclusive, so a one-day event repeats its start. All-day events are listed first on every day
they cover, without a time:
- Month view cells and the mobile selected-day list show them above timed events.
- Week and Day views show an “All day” lane between the column headers and the time grid. The lane appears only when the visible days have all-day events, and it scrolls above 92 px.
Add event button
Section titled “Add event button”import { Calendar, type CalendarEvent } from "@nesra/ui/calendar";import { useState } from "react";
export function CalendarAddEventExample() { const [events, setEvents] = useState<CalendarEvent[]>([ { id: "demo", title: "Product demo", start: "2027-01-08T13:30", end: "2027-01-08T15:30", color: "indigo", }, ]);
return ( <Calendar className="w-full" defaultDate="2027-01-08" events={events} now={new Date("2027-01-08T07:20:00Z")} timeZone="Asia/Jakarta" weekStartsOn={1} onAddEvent={(date) => setEvents((current) => [ ...current, { id: `${date}-${current.length}`, title: "New event", start: `${date}T09:00`, end: `${date}T10:00`, color: "brand", }, ]) } /> );}With onAddEvent, each desktop Month view cell shows an outline “+” button on hover and on
keyboard focus. Selecting it calls onAddEvent with the cell’s ISO date and does not call
onDayActivate. Creating the event remains the application’s responsibility.
Controlled date and view
Section titled “Controlled date and view”import { Calendar, type CalendarEvent, type CalendarView } from "@nesra/ui/calendar";import { useState } from "react";
const events: CalendarEvent[] = [ { id: "standup", title: "Friday standup", start: "2027-01-08T09:00", end: "2027-01-08T09:30" }, { id: "demo", title: "Product demo", start: "2027-01-08T13:30", end: "2027-01-08T15:30", color: "indigo", }, { id: "inspection", title: "House inspection", start: "2027-01-09T11:00", end: "2027-01-09T12:00", color: "orange", dot: true, },];
export function CalendarControlledExample() { const [date, setDate] = useState("2027-01-08"); const [view, setView] = useState<CalendarView>("day"); const [message, setMessage] = useState("Choose an event or a day.");
return ( <div className="grid w-full gap-nesra-spacing-md"> <Calendar date={date} events={events} now={new Date("2027-01-08T07:20:00Z")} timeZone="Asia/Jakarta" view={view} onDateChange={setDate} onDayActivate={(day) => setMessage(`Activated ${day}`)} onEventClick={(event) => setMessage(`Opened ${event.title}`)} onViewChange={setView} /> <p aria-live="polite" className="type-nesra-body-small-regular text-nesra-text-body"> {date} · {view} · {message} </p> </div> );}onDateChange fires for header navigation, a day click, and arrow keys. onDayActivate fires for a
day click or Enter and Space on a focused day. onEventClick fires for an event click or Enter and
Space on an event. Opening, creating, and editing events remain the application’s responsibility.
Mobile
Section titled “Mobile”import { Calendar, type CalendarEvent } from "@nesra/ui/calendar";
const events: CalendarEvent[] = [ { id: "1", title: "Friday standup", start: "2027-01-08T09:00", end: "2027-01-08T09:30" }, { id: "2", title: "Olivia x Riley", start: "2027-01-08T10:00", end: "2027-01-08T11:00", color: "brand", }, { id: "3", title: "Product demo", start: "2027-01-08T13:30", end: "2027-01-08T15:30", color: "indigo", }, { id: "4", title: "Lunch with Olivia", start: "2027-01-07T12:00", end: "2027-01-07T13:00", color: "green", }, { id: "5", title: "House inspection", start: "2027-01-09T11:00", end: "2027-01-09T12:00", color: "orange", },];
export function CalendarMobileExample() { return ( <div className="w-[375px] max-w-full"> <Calendar defaultDate="2027-01-08" events={events} now={new Date("2027-01-08T07:20:00Z")} timeZone="Asia/Jakarta" weekStartsOn={1} /> </div> );}In a container narrower than 640 px, month cells show up to three colored dots and a “+N” count. The selected day’s events are listed below the grid. Week and Day views show a seven-day strip and a single day column.
Locale and time zone
Section titled “Locale and time zone”import { Calendar, type CalendarEvent } from "@nesra/ui/calendar";import { NesraI18nProvider, type NesraMessages } from "@nesra/ui/i18n";
const events: CalendarEvent[] = [ { id: "1", title: "Rapat mingguan", start: "2027-01-04T09:00", end: "2027-01-04T10:00", color: "blue", }, { id: "2", title: "Makan siang tim", start: "2027-01-08T12:00", end: "2027-01-08T13:00", color: "green", },];
const messages: NesraMessages = { "Day view": "Tampilan hari", "Week view": "Tampilan minggu", "Month view": "Tampilan bulan", Today: "Hari ini", "Previous month": "Bulan sebelumnya", "Next month": "Bulan berikutnya", "Previous week": "Minggu sebelumnya", "Next week": "Minggu berikutnya", "Previous day": "Hari sebelumnya", "Next day": "Hari berikutnya", "Week {week}": "Minggu {week}", "Week of {date}": "Minggu {date}", "{count} more…": "{count} lainnya…", "{count} more event on {date}": "{count} acara lainnya pada {date}", "{count} more events on {date}": "{count} acara lainnya pada {date}", "{date}, {count} event": "{date}, {count} acara", "{date}, {count} events": "{date}, {count} acara", "Events on {date}": "Acara pada {date}", "No events": "Tidak ada acara", "All day": "Sepanjang hari", "Add event": "Tambah acara", "Add event on {date}": "Tambah acara pada {date}", "Event details": "Detail acara",};
export function CalendarLocaleExample() { return ( <NesraI18nProvider messages={messages}> <Calendar className="w-full" defaultDate="2027-01-08" events={events} locale="id-ID" timeZone="Asia/Jakarta" /> </NesraI18nProvider> );}locale formats dates, weekday names, and times. It also sets the first day of the week unless
weekStartsOn is given. The Week badge always shows the ISO 8601 week number.
View names, Today, navigation names, the Week badge, “N more…”, “All day”, and the other built-in
text come from NesraI18nProvider. The example translates every Calendar message. The
mini calendar’s month and year controls follow the Date Picker messages.
start and end are wall-clock times in the calendar’s time zone. Calendar never converts them.
Convert stored instants to YYYY-MM-DDTHH:mm in the same zone before passing them in. timeZone
resolves only today, the date icon, and the current-time marker.
Light and Dark
Section titled “Light and Dark”Calendar follows the page theme through .dark or data-theme="dark".
| Part | Figma variable | CSS token |
|---|---|---|
| Surface, header, cells | Surface/popover-bg-neutral, 1px Stroke/stroke-border |
--nesra-surface-popover-bg-neutral, --nesra-stroke-border |
| Outer shadow | 0 1px 2px Shadow/shadow-xs |
--nesra-shadow-xs |
| Week and Day column header row | 0 1px 2px and 0 1px 3px Shadow/shadow-lg-01 |
--nesra-shadow-lg-01 |
| Outside-month cell | Surface/card-bg-gray, Text/text-support |
--nesra-surface-card-bg-gray, --nesra-text-support |
| Cell hover | Action/tertiary-hover |
--nesra-action-tertiary-hover |
| Selected date | Foundation/bg-brand-primary, Text/text-on-brand |
--nesra-foundation-bg-brand-primary, --nesra-text-on-brand |
| Today in a month cell | Categorical/Neutral/subtle-hover |
--nesra-categorical-neutral-subtle-hover |
| Today in a column header | Foundation/bg-gray |
--nesra-foundation-bg-gray |
| Row labels | Foundation/bg-gray, Text/text-support |
--nesra-foundation-bg-gray, --nesra-text-support |
| Date icon | Foundation/bg-gray, Text/text-support, Text/text-brand-primary |
--nesra-foundation-bg-gray, --nesra-text-support, --nesra-text-brand-primary |
| Time marker | Icon/icon-brand-primary, Text/text-brand-primary |
--nesra-icon-brand-primary, --nesra-text-brand-primary |
| Event | Categorical/*/subtle, */border, */foreground, hover */subtle-hover |
--nesra-categorical-*-subtle, -border, -foreground, -subtle-hover |
| Event dot | Categorical/*/base |
--nesra-categorical-*-base |
| Add event button | Action/secondary-default, Stroke/stroke-border, Icon/icon-neutral |
--nesra-action-secondary-default, --nesra-stroke-border, --nesra-icon-neutral |
| Add event button shadow | 0 1px 2px Shadow/shadow-10 |
--nesra-shadow-10 |
| Side panel dividers | 1px Stroke/stroke-border |
--nesra-stroke-border |
| Event details title | Text/text-headline |
--nesra-text-headline |
| Event details date and time | Text/text-support, Icon/icon-muted |
--nesra-text-support, --nesra-icon-muted |
| All-day lane label | Foundation/bg-gray, Text/text-support |
--nesra-foundation-bg-gray, --nesra-text-support |
Event color values follow Figma’s event color names. Two of them use a differently named
categorical role:
color |
Categorical role |
|---|---|
gray |
Neutral |
brand |
Violet |
green |
Teal |
blue |
Blue |
indigo |
Indigo |
purple |
Purple |
pink |
Pink |
orange |
Orange |
yellow |
Yellow |
Primary buttons passed in actions, such as Add event, use text-on-brand and icon-on-brand
through Button.
Accessibility
Section titled “Accessibility”- The month view is an ARIA grid named by its month and year. Week and Day views are grids named by
their week or date. Each day is a grid cell with its full date and event count as its name.
The selected day has
aria-selected="true", and today hasaria-current="date". - The grid has one tab stop, on the selected day. Arrow Left and Right move one day. Arrow Up and Down move one week, or one day in Day view. Home and End move to the week’s edges. Page Up and Page Down move one month in Month view, and one week or day in the other views. Shift plus Page Up or Page Down moves one year in Month view.
- From the selected day, Tab reaches that day’s add event button, events, and “more” button. Controls in other days are not tab stops. The add event button is named “Add event on” and the full date, and its tooltip reads “Add event”.
- The all-day lane is a grid row with an “All day” row header. An all-day event’s name ends with “All day” instead of a time range, for example “Team offsite, Wednesday, January 6, 2027 – Thursday, January 7, 2027, All day”.
- The side panel’s event details are a region named “Event details”. The mini calendar is the Date Picker grid, and choosing a day there keeps focus on the mini calendar.
- Each event is a button, or a link when it has an
href. Its accessible name is the title, full date, and time range, for example “Product demo, Friday, January 8, 2027, 1:30 PM – 3:30 PM”. - The title announces navigation through
aria-live="polite". The current-time marker and hour labels are hidden from assistive technology because event names include their times. - The consuming page labels the region around Calendar when a page has several calendars, and gives
icon-only
actionsan accessible name.
API reference
Section titled “API reference”| Prop | Type | Default | Effect |
|---|---|---|---|
events |
readonly CalendarEvent[] |
[] |
Events to draw. Invalid times and an end not after start are skipped. |
date |
ISO date string | — | Controls the selected date. The visible month, week, or day contains it. |
defaultDate |
ISO date string | today | Sets the initial uncontrolled date. An invalid date falls back to today. |
onDateChange |
(date: string) => void |
— | Receives the date chosen by navigation, a click, or a key. |
view |
"month" | "week" | "day" |
— | Controls the view. |
defaultView |
"month" | "week" | "day" |
"month" |
Sets the initial uncontrolled view. |
onViewChange |
(view: CalendarView) => void |
— | Receives the view chosen from the menu or a “more” button. |
onEventClick |
(event: CalendarEvent) => void |
— | Receives the clicked or activated event. |
onDayActivate |
(date: string) => void |
— | Receives a clicked day, or a focused day activated with Enter or Space. |
onAddEvent |
(date: string) => void |
— | Shows the Month view “+” button and receives its cell’s date. |
sidePanel |
boolean |
true |
Shows the Day view side panel in the Desktop layout. |
renderEventDetails |
(event: CalendarEvent) => ReactNode |
— | Renders content below the date and time in the side panel. |
renderEventActions |
(event: CalendarEvent) => ReactNode |
— | Renders actions beside the event title in the side panel. |
actions |
ReactNode |
— | Renders application actions at the end of the header. |
locale |
BCP 47 locale string | "en-US" |
Formats dates, weekdays, and times. |
timeZone |
IANA time zone string | runtime zone | Resolves today and the current-time marker. |
weekStartsOn |
0–6 (Sunday–Saturday) |
locale’s first day | Sets the first column of the month and week views. |
now |
Date |
current time | Fixes the current instant. Without it, the clock updates every minute. |
className |
string |
— | Adds classes to the Calendar root. |
Calendar forwards its ref and other native div props to the root element.
CalendarEvent
Section titled “CalendarEvent”| Field | Type | Default | Effect |
|---|---|---|---|
id |
string |
required | Identifies the event. Must be unique within events. |
title |
string |
required | Sets the visible title and the start of the event’s name. |
start |
YYYY-MM-DDTHH:mm |
required | Sets the wall-clock start. All-day: the first day. |
end |
YYYY-MM-DDTHH:mm |
required | Sets the exclusive end. All-day: the inclusive last day. |
allDay |
boolean |
false |
Draws the event on whole days without a time. |
color |
CalendarEventColor |
"gray" |
Selects one of the nine Figma event colors. |
dot |
boolean |
false |
Shows the colored dot beside the title. |
href |
string |
— | Renders the event as a link to this URL. |
CalendarEventColor is "gray" | "brand" | "green" | "blue" | "indigo" | "purple" | "pink" | "orange" | "yellow". A timed event needs an end after start. An all-day event takes
YYYY-MM-DD dates, or the date part of YYYY-MM-DDTHH:mm values, and needs an end on or after
start. Calendar skips events that break these rules.
Behavior Figma does not define
Section titled “Behavior Figma does not define”Figma does not define the following. The code behaves as described:
- Add event button position: Figma places the “+” below the events in a 208 px tall cell. The composed Month view cells are about 156 px tall, so the code places the button at the cell’s top-end corner, on the date row.
- Add event button keyboard and touch: the button also shows on keyboard focus and is a tab stop of the selected day. It is not rendered in the Mobile layout or in Week and Day views.
- Side panel breakpoint and selection: Figma draws the panel only in the 1280 px Desktop frame. The code shows it in the whole Desktop layout, from 640 px of container width. Its event is chosen as described in “Day view side panel”.
- Side panel scrolling: Figma fades the bottom 96 px of the details. The code scrolls the details without a fade, so the last line stays readable.
- All-day events: Figma has no all-day design. The code reuses the Month view event style without a time, repeats multi-day events in each day, and adds the “All day” lane to Week and Day views.
Styling uses colors, layout, and shape and elevation tokens.