Calendar

Installation

pnpm dlx @docyrus/cli add @docyrus/rn-calendar

pnpm add date-fns react-native-gesture-handler react-native-reanimated @shopify/flash-list

The native calendar mirrors the web Calendar API 1:1 (same IEvent model, same prop names, same ui.calendar.* translation keys) and adapts it to touch: popovers become bottom sheets, right-click / hover become long-press, HTML5 drag becomes a gesture-handler long-press drag with a reanimated ghost.

Expo Configuration

Month and weekday names use the device locale through the optional react-native-localize peer. Add its plugin to app.config.ts when you install it:

{
  plugins: [
    ['react-native-localize', { locales: ['en', 'tr'] }]
  ]
}

The app must be wrapped in GestureHandlerRootView (drag & drop, resize, taps).

Usage

import { Calendar, type IEvent } from '@/components/docyrus-native/calendar';

const events: IEvent[] = [
  {
    id: 1,
    title: 'Team Meeting',
    startDate: '2026-03-04T10:00:00.000Z',
    endDate: '2026-03-04T11:00:00.000Z',
    color: 'blue',
    description: 'Weekly sync',
    user: { id: 'u1', name: 'Ada Lovelace', picturePath: null }
  }
];

<Calendar
  events={events}
  users={[{ id: 'u1', name: 'Ada Lovelace', picturePath: null }]}
  defaultView="month"
  weekStartsOn={1}
  onEventCreate={event => api.create(event)}
  onEventUpdate={event => api.update(event)}
  onEventDelete={id => api.remove(id)}
  onEventDrop={(event, start, end) => api.move(event.id, start, end)}
  onVisibleRangeChange={(range, view) => refetch(range)}
/>

Period timelines

<Calendar
  events={projectPlans}
  defaultView="year-timeline"
  visibleViews={['year-timeline', 'quarter', '13weeks']}
  defaultYearTimelineMode="continuous"
  defaultQuarterMode="single"
  timelineMaxLanes={4}
/>

Refetch without resetting the view

const { data, isFetching, isLoading } = useQuery(/* … */);

<Calendar
  events={data ?? []}
  isLoading={isLoading}      // first load → skeleton (unmounts)
  isRefreshing={isFetching}  // later fetches → overlay, keeps view / date / scroll
/>

Controlled / persisted settings

// Persist the settings blob (badge style, 24h format, agenda grouping,
// timeline modes, last view) through lib/storage — mount a sync store with
// <DocyStorageProvider> (expo-sqlite kv-store or MMKV).
<Calendar events={events} persistSettings />

// Or own the settings yourself:
<Calendar
  events={events}
  settings={{ use24HourFormat: false }}
  onSettingsChange={settings => save(settings)}
/>

Custom create / open flows

<Calendar
  events={events}
  onCreateEvent={date => router.push({ pathname: '/events/new', params: { date: date.toISOString() } })}
  onEventClick={event => router.push(`/events/${event.id}`)}
/>

Views

Timeline views scroll horizontally on phones with a sticky row gutter. year-timeline and quarter support continuous (periods stacked, more load on scroll, capped at ±12) and single navigation; 13weeks is always single. A row shows timelineMaxLanes lanes and collapses the rest into +N more (only that row expands).

Interactions

API Reference

Calendar

CalendarProvider accepts every prop above except isLoading, variant, size, showFab, className and style, plus children.

IEvent

IUser

CalendarFilterItem

CalendarSettings

The header settings sheet edits every field except view (the tab strip does).

useCalendar()

Returns CalendarContextValue: selectedDate / setSelectedDate, view / setView, the settings getters + setters (badgeVariant, use24HourFormat / toggleTimeFormat, agendaModeGroupBy, yearTimelineMode, quarterMode, settings), filters (selectedColors, filterEventsBySelectedColors, selectedUserId, filterEventsBySelectedUser, selectedFilterId, onFilterChange, clearFilter), events (filtered) / allEvents, CRUD (addEvent, updateEvent, removeEvent, moveEvent), flows (requestCreate, openEvent, openEditForm, openDayEvents), the grid config (weekStartsOn, startHour, endHour, hourSlotHeight, cellMinHeight, cellMinWidth, timelineMaxLanes, minDate, maxDate) and timelineRange / reportTimelineRange.

Components

Type Exports

Translations

All copy goes through useUiTranslation() with the web ui.calendar.* keys (addEvent, settings, dotBadge, 24HourFormat, agendaGroupBy, yearTimelineDisplay, quarterDisplay, continuous, singleYear, singleQuarter, viewMonth … view13Weeks, previousMonth / nextQuarter … nextPeriod, eventsOn, noEvents, noResults, searchPlaceholder, responsible, startDate, endDate, deleteEvent, deleteConfirm, loading, more, showLess, …). Native-only keys: ui.calendar.today, ui.calendar.events, ui.calendar.allDay, ui.calendar.startTime, ui.calendar.selectDate, ui.calendar.selectTime, ui.calendar.endTimeError, ui.calendar.currentUser, ui.calendar.event, ui.calendar.sidebar, ui.calendar.resizeEvent.

Migration from the previous native API