react-appointment-scheduler

A production-ready React scheduler component for appointment management. Features day/week views, drag-and-drop rescheduling, color-coded appointment types, and a beautiful, minimal UI.

Features

• Day & Week Views - Toggle between single day and full week layouts
• Drag & Drop - Reschedule appointments by dragging to new times or days
• Color-Coded Types - 4 customizable service types with distinct colors
• Overlap Handling - Automatically stacks overlapping appointments
• Detail Views - Modal or side panel for appointment details
• Responsive - Desktop-first with mobile support
• TypeScript - Full type definitions included
• Accessible - Keyboard navigation and ARIA labels

Installation

npm install react-appointment-scheduler

Peer Dependencies

This package requires React 18+ or 19+:

npm install react react-dom

Styles

Import the component styles in your app:

import 'react-appointment-scheduler/styles.css';

Usage

Basic Example

import { Scheduler, type Appointment } from 'react-appointment-scheduler';
import 'react-appointment-scheduler/styles.css';

const appointments: Appointment[] = [
  {
    id: '1',
    clientName: 'Sarah Johnson',
    serviceType: 'Volume',
    artist: 'Emma Wilson',
    startTime: new Date('2024-01-15T09:00:00'),
    duration: 150,
    phone: '(555) 123-4567',
    notes: 'First-time client',
  },
  {
    id: '2',
    clientName: 'Emily Chen',
    serviceType: 'Classic',
    startTime: new Date('2024-01-15T14:00:00'),
    duration: 90,
  },
];

function App() {
  return (
    <div style={{ height: '600px' }}>
      <Scheduler
        appointments={appointments}
        startHour={8}
        endHour={21}
        view="week"
        detailDisplay="modal"
        onSelectAppointment={(apt) => console.log('Selected:', apt)}
        onCreateAppointment={(start, end) => console.log('Create:', start, end)}
        onRescheduleAppointment={(id, newTime) => console.log('Reschedule:', id, newTime)}
      />
    </div>
  );
}

API Reference

<Scheduler /> Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | appointments | Appointment[] | required | Array of appointments to display | | startHour | number | 8 | Working hours start (0-23) | | endHour | number | 21 | Working hours end (0-23) | | view | 'day' \| 'week' | 'week' | Initial view mode | | selectedDate | Date | today | Initially selected/focused date | | detailDisplay | 'modal' \| 'panel' | 'modal' | How to show appointment details | | onSelectAppointment | (apt: Appointment) => void | - | Called when clicking an appointment | | onCreateAppointment | (start: Date, end: Date) => void | - | Called when clicking an empty slot | | onRescheduleAppointment | (id: string, newStart: Date) => void | - | Called after drag-and-drop |

Appointment Type

interface Appointment {
  id: string;
  clientName: string;
  serviceType: 'Classic' | 'Hybrid' | 'Volume' | 'Refill';
  artist?: string;
  startTime: Date;
  duration: number; // minutes
  notes?: string;
  phone?: string;
}

Service Types & Colors

| Type | Color | Use Case Example | |------|-------|------------------| | Classic | Rose/Pink | Standard service | | Hybrid | Lavender/Violet | Mixed/combination service | | Volume | Peach/Amber | Premium/extended service | | Refill | Sage/Emerald | Maintenance/follow-up |

Advanced Usage

Server-Side Rendering (SSR)

The package is fully compatible with SSR frameworks like Next.js, Remix, and others. When using with Next.js App Router:

'use client'; // Required for client components

import { Scheduler } from 'react-appointment-scheduler';
import 'react-appointment-scheduler/styles.css';

export default function SchedulerPage() {
  return (
    <div style={{ height: '600px' }}>
      <Scheduler
        appointments={appointments}
        startHour={8}
        endHour={21}
      />
    </div>
  );
}

The component automatically handles SSR gracefully - all browser APIs (localStorage, window, document) are safely accessed only on the client side.

Dark/Light Theme Support

The package includes built-in theme support. See THEME_DOCS.md for detailed documentation.

import { ThemeToggle, initializeTheme } from 'react-appointment-scheduler';
import { useEffect } from 'react';

function App() {
  useEffect(() => {
    initializeTheme();
  }, []);

  return (
    <div>
      <ThemeToggle />
      <Scheduler {...props} />
    </div>
  );
}

Custom Styling

The component uses CSS custom properties (CSS variables) for theming. You can customize colors by overriding the CSS variables:

:root {
  /* Override service type colors */
  --color-rose-400: #your-custom-color;
  --color-violet-400: #your-custom-color;
  --color-amber-400: #your-custom-color;
  --color-emerald-400: #your-custom-color;
}

Service type CSS classes are available for styling:

• .service-classic - Rose/Pink theme
• .service-hybrid - Violet/Lavender theme
• .service-volume - Amber/Peach theme
• .service-refill - Emerald/Sage theme

Using Individual Components

You can import and use sub-components for custom layouts:

import {
  DayView,
  WeekView,
  TimeGrid,
  AppointmentBlock,
  useScheduler,
  useDragDrop,
} from 'react-appointment-scheduler';

Utility Functions

import {
  formatTime,
  formatFullDate,
  calculateAppointmentLayouts,
  filterAppointmentsByDay,
} from 'react-appointment-scheduler';

// Format time: "9:00 AM"
formatTime(new Date());

// Format date: "Monday, January 15, 2024"
formatFullDate(new Date());

Styling

The component container should have a defined height:

<div style={{ height: '600px' }}>
  <Scheduler appointments={appointments} />
</div>

Or use viewport height:

<div style={{ height: 'calc(100vh - 200px)' }}>
  <Scheduler appointments={appointments} />
</div>

TypeScript

Full TypeScript support with exported types:

import type {
  Appointment,
  SchedulerProps,
  ServiceType,
  ViewMode,
  DetailDisplayMode,
  AppointmentLayout,
  TimeSlot,
} from 'react-appointment-scheduler';

License

MIT