Skip to content
Patro

Quick Start

React Quick Start

@thaparoyal/calendar-react provides prebuilt compound components for every calendar feature. Unlike the headless Vue/Svelte packages, the React package includes fully styled UI components out of the box.

Installation

Terminal window
npm install @thaparoyal/calendar-react @thaparoyal/calendar-core

Import the theme CSS in your app entry point:

import '@thaparoyal/calendar-core/themes/themes.css';

Components

ComponentPurpose
CalendarSingle date selection with month/year pickers
DatePickerInput field with calendar dropdown
RangeCalendarSelect a date range (start → end)
MultiCalendarMultiple months side by side

Hooks

HookPurpose
useCalendarHeadless calendar state and actions
useSelectionSelection logic for single/range/multiple modes
useDatePickerDate picker state (open/close, input, calendar)
useDateConverterAD↔BS date conversion utilities

Compound Component Pattern

Every React component uses a compound component pattern. You compose your calendar from small, focused sub-components:

import { useState } from 'react';
import { Calendar } from '@thaparoyal/calendar-react';
import type { CalendarDate } from '@thaparoyal/calendar-react';
import '@thaparoyal/calendar-core/themes/themes.css';


function App() {
  const [date, setDate] = useState<CalendarDate | null>(null);


  return (
    <div data-theme="ocean">
      <Calendar.Root
        config={{ calendarType: 'BS', locale: 'en' }}
        value={date}
        onValueChange={setDate}
      >
        <Calendar.Header>
          <Calendar.PrevButton />
          <Calendar.Title />
          <Calendar.NextButton />
        </Calendar.Header>
        <Calendar.Grid>
          <Calendar.GridHead />
          <Calendar.GridBody />
        </Calendar.Grid>
      </Calendar.Root>
    </div>
  );
}

Each sub-component (Calendar.Header, Calendar.Title, etc.) renders its portion of the UI and reads shared state from React Context internally.

Calendar Types

  • BS (Bikram Sambat) — Nepali calendar system
  • AD (Anno Domini) — Gregorian calendar
// BS Calendar
<Calendar.Root config={{ calendarType: 'BS', locale: 'en' }}>


// AD Calendar
<Calendar.Root config={{ calendarType: 'AD', locale: 'en' }}>


// Nepali Numerals
<Calendar.Root config={{ calendarType: 'BS', locale: 'ne' }}>

Themes

Wrap your calendar in a container with data-theme attribute:

<div data-theme="ocean">
  <Calendar.Root>...</Calendar.Root>
</div>

Available themes: default, dark, ocean, ocean-dark, forest, forest-dark, sunset, sunset-dark, royal, royal-dark, nepal, nepal-dark, lavender, midnight, rose, mint, amber, slate, coral, indigo.

Quick Examples

Date Picker

import { DatePicker } from '@thaparoyal/calendar-react';


<DatePicker.Root
  config={{ calendarType: 'BS', locale: 'en' }}
  value={date}
  onValueChange={setDate}
>
  <DatePicker.Input placeholder="Select date..." />
  <DatePicker.Trigger />
  <DatePicker.Content>
    <DatePicker.Calendar />
  </DatePicker.Content>
</DatePicker.Root>

Range Calendar

import { RangeCalendar } from '@thaparoyal/calendar-react';
import type { DateRangeValue } from '@thaparoyal/calendar-react';


const [range, setRange] = useState<DateRangeValue | null>(null);


<RangeCalendar.Root
  config={{ calendarType: 'BS', locale: 'en' }}
  value={range}
  onValueChange={setRange}
>
  <RangeCalendar.Header>
    <RangeCalendar.PrevButton />
    <RangeCalendar.Title />
    <RangeCalendar.NextButton />
  </RangeCalendar.Header>
  <RangeCalendar.Grid>
    <RangeCalendar.GridHead />
    <RangeCalendar.GridBody />
  </RangeCalendar.Grid>
</RangeCalendar.Root>

Multi-Calendar

import { MultiCalendar } from '@thaparoyal/calendar-react';


<MultiCalendar.Root
  numberOfMonths={2}
  mode="range"
  config={{ calendarType: 'BS', locale: 'en' }}
  value={range}
  onValueChange={setRange}
>
  <MultiCalendar.Header>
    <MultiCalendar.PrevButton />
    <MultiCalendar.Title />
    <MultiCalendar.NextButton />
  </MultiCalendar.Header>
  <MultiCalendar.Calendars />
</MultiCalendar.Root>

Next Steps