useDocyrusCalendar

Installation

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

pnpm add @docyrus/api-client @docyrus/app-utils @tanstack/react-query

This is a port of the web hook with the same signature. It builds on useDocyrusDataGrid, which supplies saved views, the toolbar, filters, search and field metadata. Its own items query then requests only the columns the calendar needs.

calendarProviderProps is ready to spread onto the native Calendar, which supports all eight views (including year-timeline, quarter and 13weeks). It passes:

• isRefreshing (from itemsQuery.isFetching)
• the timeline options
• the user filterItems
• onEventCreate / onEventUpdate / onEventDelete / onEventDrop, each calling the Docyrus API

With enableDateRangeFilter, the query adds an overlap rule (start <= rangeEnd AND end >= rangeStart) and refetches whenever the visible range changes. The hook needs an authenticated RestApiClient and a QueryClientProvider above it.

Usage

import { useDocyrusClient } from '@docyrus/signin/react-native';

import { Calendar } from '@/components/docyrus-native/calendar';
import { useDocyrusCalendar } from '@/hooks/docyrus-native/use-docyrus-calendar';

export function EventsCalendar() {
  const client = useDocyrusClient();

  const cal = useDocyrusCalendar({
    client: client!,
    appSlug: 'base',
    dataSourceSlug: 'event',
    startDateFieldSlug: 'start_date',
    endDateFieldSlug: 'end_date',
    titleFieldSlug: 'subject',
    descriptionFieldSlug: 'description',
    enableDateRangeFilter: true,
    persistState: true
  });

  // Render a skeleton only on the very first load — passing `isLoading` on
  // every refetch would unmount the calendar and reset its view + date.
  if (!cal.hasLoadedOnce) return null;

  return (
    <>
      {cal.toolbar}
      <Calendar {...cal.calendarProviderProps} />
    </>
  );
}

API Reference

Options (UseDocyrusCalendarOptions<TData>)

Extends every useDocyrusDataGrid option except data, enableItemsQuery, showSelectColumn, enableRowMarkers and collection, which the calendar owns.

Result (UseDocyrusCalendarResult<TData>)

Native deltas

• toolbar / table come from the native useDocyrusDataGrid, which stacks the toolbar for small screens.
• With enableDateRangeFilter, calendarProviderProps.onVisibleRangeChange is already wired to setVisibleRange. On web you wire it yourself. Pass your own onVisibleRangeChange after the spread to override it. Identical ranges are ignored.
• The items query keeps the previous result while a new range loads (keepPreviousData). Navigating shows the isRefreshing spinner over the current events instead of clearing the calendar.

Type Exports