DayFlowCalendar Component

DayFlowCalendar is the high-level component that renders the currently selected view, handles layout, and wires optional UI like the sidebar or event detail dialog. Pair it with useCalendarApp and the view factory helpers to get a fully functioning calendar with minimal code.

Basic Usage

import {
  DayFlowCalendar,
  useCalendarApp,
  createWeekView,
  ViewType,
} from '@dayflow/react'; // or '@dayflow/vue', '@dayflow/svelte', '@dayflow/angular'
import { createSidebarPlugin } from '@dayflow/plugin-sidebar';
import '@dayflow/core/dist/styles.css';

export function CalendarDemo() {
  const calendar = useCalendarApp({
    views: [createWeekView()],
    defaultView: ViewType.WEEK,
    initialDate: new Date(),
    events: [],
    plugins: [createSidebarPlugin()],
  });

  return <DayFlowCalendar calendar={calendar} />;
}

The component receives the calendar object from useCalendarApp, reads the active view, and renders the corresponding view component. Any toolbar or custom UI can live beside DayFlowCalendar, but it already includes:

An optional calendar sidebar (added through createSidebarPlugin).
Event detail dialog support (driven by useEventDetailDialog or a custom renderer).
Automatic layout updates when calendars are toggled or views change.

Props

Prop	Type	Required	Description
`calendar`	`UseCalendarAppReturn`	Required	Result of `useCalendarApp`. Provides state, registered views, sidebar config, and calendar actions.
`collapsedSafeAreaLeft`	`number`	Optional	Left padding (px) when the sidebar is collapsed, e.g. to account for a Mac traffic-light area.
`search`	`CalendarSearchProps`	Optional	Configuration for the built-in search functionality.

Slot-based customisation (event content, detail panel content, detail dialog, color picker, etc.) is handled through framework-native slots rather than props. See Content Slots for the full list.

Search Configuration

The search prop allows you to customize the built-in search behavior. By default, it searches event titles and descriptions locally.

<DayFlowCalendar
  calendar={calendar}
  search={{
    debounceDelay: 500,
    emptyText: 'No events found',
    onSearch: async keyword => {
      // Custom async search (e.g., from an API)
      return fetch(`/api/search?q=${keyword}`).then(res => res.json());
    },
  }}
/>

Search Props

Option	Description
`debounceDelay`	Time in milliseconds to wait before triggering a search.
`onSearch`	Async function to fetch results based on a keyword.
`customSearch`	Synchronous function to filter events locally with custom logic.
`onResultClick`	Optional callback triggered when a search result is clicked. Includes a `defaultAction` callback to invoke the built-in navigation logic (navigating to the event date, highlighting the event, and closing the search UI on mobile). If you don't call `defaultAction()`, you must handle the navigation and UI state yourself.
`emptyText`	Text to display when no results are found.

The sidebar is added by installing the @dayflow/plugin-sidebar plugin:

import { createSidebarPlugin } from '@dayflow/plugin-sidebar';

const calendar = useCalendarApp({
  views: [createWeekView()],
  plugins: [
    createSidebarPlugin({
      width: 280,
      initialCollapsed: false,
      createCalendarMode: 'modal', // 'inline' or 'modal'
    }),
  ],
});

return <DayFlowCalendar calendar={calendar} />;

When createSidebarPlugin() is added to plugins, the default sidebar (DefaultCalendarSidebar) is rendered with calendar filters and toggle-all controls.
You can customize width, default collapsed state, creation mode (createCalendarMode), or supply your own renderer via render or renderSidebarHeader. Your renderer receives CalendarSidebarRenderProps (for render) or SidebarHeaderSlotArgs (for renderSidebarHeader), so you can reuse its helper callbacks and data.

Event Detail Experiences

DayFlow ships with three options for event details:

Default panel mode – when useEventDetailDialog is false (the default), clicking an event opens the built-in floating DefaultEventDetailPanel. Use the eventDetailContent slot to replace the panel body while keeping the default chrome.
Dialog mode – set useEventDetailDialog: true in useCalendarApp to enable the built-in centered modal. Use the eventDetailDialog slot to replace it with your own dialog UI.
Opt out entirely – set useEventDetailPanel: false in useCalendarApp to suppress the floating panel when you have your own event modals driven by app callbacks.

// Suppress the built-in panel — use your own modal triggered elsewhere
const calendar = useCalendarApp({
  ...
  useEventDetailPanel: false,
});

return <DayFlowCalendar calendar={calendar} />;

// Custom panel content (keeps the default panel chrome)
<DayFlowCalendar
  calendar={calendar}
  eventDetailContent={({ event, onClose }) => (
    <div className='p-4'>
      <h2>{event.title}</h2>
      <button onClick={onClose}>Close</button>
    </div>
  )}
/>

// Custom dialog (requires useEventDetailDialog: true in useCalendarApp)
<DayFlowCalendar
  calendar={calendar}
  eventDetailDialog={({ event, isOpen, onClose }) => (
    <MyDialog isOpen={isOpen} onClose={onClose}>
      <EventForm event={event} />
    </MyDialog>
  )}
/>

In short, DayFlowCalendar handles the orchestration layer—layout, sidebar wiring, and event detail plumbing—so you can focus on configuring useCalendarApp and building the surrounding product experience.