A full-featured calendar component supporting day, week, and month time ranges with horizontal and vertical layouts, team member columns, and event rendering.
Example
Preview
Code
Props
Calendar Props
Prop
Type
Default
Description
events
CalendarEventType[]
—
Array of calendar events to display. Each event has id, title, start, end, optional color and memberId.
members
CalendarTeamMember[]
—
Array of team members for horizontal column layout. Each member has id, name, initials, and optional role/avatarColor.
initialDate
Date
—
The initial date the calendar focuses on.
initialLayout
'horizontal' | 'vertical'
'horizontal'
The initial layout mode. Horizontal shows a timeline grid; vertical shows a list.
initialTimeRange
'day' | 'week' | 'month'
'day'
The initial time range to display.
horizontalConfig
CalendarHorizontalConfig
—
Configuration for the horizontal timeline: startHour, endHour, slotMinutes, slotWidth, slotHeight, timeColumnWidth, memberColumnWidth.
onDateSelect
(date: Date) => void
—
Callback when a date is selected.
onEventPress
(event: CalendarEventType) => void
—
Callback when an event is pressed.
onMonthChange
(year: number, month: number) => void
—
Callback when the displayed month changes.
onViewChange
(layout: CalendarLayout) => void
—
Callback when the layout mode changes.
onTimeRangeChange
(timeRange: CalendarTimeRange) => void
—
Callback when the time range changes.
renderEvent
(event: CalendarEventType) => React.ReactNode
—
Custom render function for events.
className
string
—
NativeWind utility classes for the calendar container.
children
React.ReactNode
—
Compose the calendar UI using sub-components like CalendarHeader, CalendarViewSwitcher, and layout views.
CalendarHeader Props
Prop
Type
Default
Description
className
string
—
NativeWind utility classes for the header.
CalendarViewSwitcher Props
Prop
Type
Default
Description
target *
'timeRange' | 'layout'
—
Which dimension the switcher toggles — time range (day/week/month) or layout (horizontal/vertical).
className
string
—
NativeWind utility classes for the switcher.
CalendarHorizontalView Props
Prop
Type
Default
Description
className
string
—
NativeWind utility classes for the horizontal timeline.
CalendarVerticalView Props
Prop
Type
Default
Description
className
string
—
NativeWind utility classes for the vertical list view.
CalendarMonthView Props
Prop
Type
Default
Description
className
string
—
NativeWind utility classes for the month grid.
CalendarLegend Props
Prop
Type
Default
Description
items *
CalendarLegendItem[]
—
Array of { color, label } items to render in the legend.
className
string
—
NativeWind utility classes for the legend container.
Usage Guidelines
When to use
Use Calendar to display schedules, appointments, or time-based events. It supports multiple views (day/week/month), horizontal timeline and vertical list layouts, and team member grouping.
Best practices
•
Use the compound component pattern — compose CalendarHeader, CalendarViewSwitcher, and view components as children of Calendar.
•
Provide a CalendarLegend when using multiple event colors so users understand the color coding.
•
Use the horizontal layout for timeline views and vertical for list-style agendas.
Accessibility
Calendar supports accessibility roles and labels on event items. Events are pressable with appropriate labels. Use onEventPress to handle selection.
Related Components
Tabs
A compound tabbed interface component with tab list, individual tabs, and content panels for organizing content into switchable views.
Badge
A compound component for displaying short status labels, counts, or tags with semantic color and variant options.
Avatar
A compound component for displaying user profile images, initials fallback, online badges, and grouped avatar stacks.