Skip to content

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.

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, renderEventDetails

The header, views, cells, and events are rendered from props. Calendar has no public parts.

January 2027
Week 1

Jan 1, 2027 – Jan 31, 2027

Monday
Tuesday
Wednesday
Thursday
Friday
Saturday
Sunday

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.

January 2027
Week 1

Jan 4, 2027 – Jan 10, 2027

Monday, January 4, 2027
Tuesday, January 5, 2027
Wednesday, January 6, 2027
Thursday, January 7, 2027
Friday, January 8, 2027
Saturday, January 9, 2027
Sunday, January 10, 2027

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.

January 8, 2027
Week 1

Friday

Friday, January 8, 2027

Product demo

Friday, Jan 8, 2027

1:30 PM – 3:30 PM

10 min before

3 guests · 2 yes · 1 awaiting

About this event

Product demo for the new dashboard, followed by questions from the team.

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.

January 2027
Week 1

Jan 4, 2027 – Jan 10, 2027

Monday, January 4, 2027
Tuesday, January 5, 2027
Wednesday, January 6, 2027
Thursday, January 7, 2027
Friday, January 8, 2027
Saturday, January 9, 2027
Sunday, January 10, 2027
All day

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.
January 2027
Week 1

Jan 1, 2027 – Jan 31, 2027

Monday
Tuesday
Wednesday
Thursday
Friday
Saturday
Sunday

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.

January 8, 2027
Week 1

Friday

Friday, January 8, 2027

Product demo

Friday, Jan 8, 2027

1:30 PM – 3:30 PM

2027-01-08 · day · Choose an event or a day.

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.

January 2027
Week 1

Jan 1, 2027 – Jan 31, 2027

Monday
Tuesday
Wednesday
Thursday
Friday
Saturday
Sunday

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.

Januari 2027
Minggu 1

1 Jan 2027 – 31 Jan 2027

Minggu
Senin
Selasa
Rabu
Kamis
Jumat
Sabtu

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.

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.

  • 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 has aria-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 actions an accessible name.
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.

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.

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.