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

``bash
npm install react-appointment-scheduler
`

$3

This package requires React 18+ or 19+:

`bash
npm install react react-dom
`

$3

Import the component styles in your app:

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

Usage

$3

`tsx
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 (



);
}
`

API Reference

$3

| 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 |

$3

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

$3

| 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

$3

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

`tsx
'use client'; // Required for client components

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

export default function SchedulerPage() {
return (



);
}
`

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

$3

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

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

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

return (



);
}
`

$3

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

`css
: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

$3

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

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

$3

`tsx
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:

`tsx



`

Or use viewport height:

`tsx



`

TypeScript

Full TypeScript support with exported types:

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

License

MIT