react-schedule-picker

Drag-to-select weekly schedule picker for React. Zero dependencies, fully typed, locale-aware.

Live Demo →

<SchedulePicker value={schedule} onChange={setSchedule} />

Features

• Drag selection — click cells, drag rectangles, or drag day/hour headers to select rows/columns
• Touch support — full mobile drag with haptic feedback
• Locale-aware — built-in en, en-US, ko, ja, zh-CN, zh-TW (week start, hour format, weekend colors, button text)
• Serializable — convert to ranges or iCalendar-style payloads for APIs and databases
• Themable — CSS custom properties, no styling library required
• Zero runtime dependencies — only React as a peer dep
• Fully typed — written in TypeScript with strict types

Installation

npm install react-schedule-picker
# or
pnpm add react-schedule-picker
# or
yarn add react-schedule-picker
# or
bun add react-schedule-picker

Import the stylesheet once at your app root:

import "react-schedule-picker/styles.css";

Quick Start

import { useState } from "react";
import { SchedulePicker, type Schedule } from "react-schedule-picker";
import "react-schedule-picker/styles.css";

export function Availability() {
  const [schedule, setSchedule] = useState<Schedule>({});

  return <SchedulePicker value={schedule} onChange={setSchedule} />;
}

The Schedule shape is Record<string, number[]> — day key ("mon" … "sun") mapped to an array of selected hours (0–23).

Common Examples

Localized to Korean

<SchedulePicker locale="ko" value={schedule} onChange={setSchedule} />

Business hours only

<SchedulePicker
  value={schedule}
  onChange={setSchedule}
  minHour={9}
  maxHour={18}
  visibleDays={["mon", "tue", "wed", "thu", "fri"]}
/>

Block out specific slots

const lunchBreak: Schedule = {
  mon: [12, 13], tue: [12, 13], wed: [12, 13], thu: [12, 13], fri: [12, 13],
};

<SchedulePicker
  value={schedule}
  onChange={setSchedule}
  disabledSlots={lunchBreak}
/>

Read-only display

<SchedulePicker value={schedule} onChange={setSchedule} readOnly />

Submit-style — fire only when the user finishes dragging

<SchedulePicker
  value={schedule}
  onChange={setSchedule}
  onSelectEnd={(final) => saveToServer(final)}
/>

Props

Core

Prop	Type	Default	Description
value	Schedule	required	Controlled schedule value
onChange	(s: Schedule) => void	required	Fires on every change, including during drag
onSelectEnd	(s: Schedule) => void	—	Fires once when a drag completes

Localization

Prop	Type	Default	Description
locale	"en" | "en-US" | "ko" | "ja" | "zh-CN" | "zh-TW"	"en"	Sets week start, hour format, weekend colors, and built-in text
weekStartsOn	"mon" | "sun" | "sat"	locale default	Override the first day of the week
weekendHighlight	Record<string, string> | "none"	locale default	Weekend text colors. "none" disables highlighting
dayLabels	Record<string, string>	locale default	Custom day header labels
messages	Partial<Messages>	locale default	Override individual built-in messages

Display

Prop	Type	Default	Description
dayAxis	"x" | "y"	"x"	"x": days as columns. "y": days as rows
visibleDays	string[]	locale default	Which days to show, and their order
minHour	number	0	Earliest hour to display
maxHour	number	23	Latest hour to display
compactHourLabels	boolean	false	Show only every 3rd hour label
formatHour	(h: number) => string	locale default	Custom hour label formatter

State

Prop	Type	Default	Description
readOnly	boolean	false	Display-only mode (no interactions)
disabled	boolean	false	Fully disabled state
disabledSlots	Schedule	—	Slots that cannot be selected

Toolbar

Prop	Type	Default	Description
presets	Preset[]	4 built-in	Preset buttons. Empty array hides the toolbar entries
hideToolbar	boolean	false	Hide the toolbar entirely

Styling

Prop	Type	Default	Description
className	string	—	Extra class on the outermost container

Localization Details

Each locale preset bundles week start, hour format, weekend colors, and translated text in one prop:

locale	Week start	Hour format	Sat / Sun	clear
"en"	Mon	14	none	Clear
"en-US"	Sun	2PM	none	Clear
"ko"	Mon	14	blue / red	초기화
"ja"	Sun	14	blue / red	クリア
"zh-CN"	Mon	14	red / red	清除
"zh-TW"	Mon	14	red / red	清除

Preset button labels (Weekday Day / Weekday Night / etc.) are translated per locale as well.

Override priority

explicit prop (dayLabels / formatHour / visibleDays / presets)
   > messages / weekStartsOn / weekendHighlight props
   > LOCALE_PRESETS[locale]
   > "en" fallback

Serialization

The internal Schedule shape is optimized for rendering. For API transport and storage, convert it with one of the bundled helpers.

toRanges(schedule, options?)

Compress consecutive hours into [start, end) ranges, keyed by ISO 8601 day-of-week (1=Mon … 7=Sun).

import { toRanges } from "react-schedule-picker";

toRanges({ mon: [9, 10, 11, 14, 15] }, { timezone: "Asia/Seoul" });
// {
//   version: 1,
//   timezone: "Asia/Seoul",
//   ranges: [
//     { day: 1, start: "09:00", end: "12:00" },
//     { day: 1, start: "14:00", end: "16:00" },
//   ],
// }

fromRanges(payload)

Inverse of toRanges. Accepts only hour-aligned input.

import { fromRanges } from "react-schedule-picker";

fromRanges({
  version: 1,
  ranges: [{ day: 1, start: "09:00", end: "12:00" }],
});
// { mon: [9, 10, 11] }

toISO(schedule, options?)

Same data as toRanges, but with iCalendar-style field names (startTime / endTime).

import { toISO } from "react-schedule-picker";

toISO({ mon: [9, 10, 11] }, { timezone: "Asia/Seoul" });
// {
//   version: 1,
//   timezone: "Asia/Seoul",
//   availability: [
//     { day: 1, startTime: "09:00", endTime: "12:00" },
//   ],
// }

Notes

• 1-hour granularity only. Sub-hour (15/30 min) is not supported.
• Ranges use half-open intervals: end is exclusive. end: "24:00" means up to midnight.
• Day keys in the raw Schedule are strings ("mon"…"sun"). ISO numeric keys appear only in serialized output.

Theming

All colors and sizes are CSS custom properties on .rsp-container. Override what you need:

.rsp-container {
  --rsp-color-selected: #34d399;
  --rsp-color-border: #d4d4d8;
  --rsp-cell-size: 40px;
  --rsp-border-radius: 12px;
}

See src/variables.css for the full list.

Requirements

• React 18+
• Modern browsers (last 2 versions of Chrome, Safari, Firefox, Edge)
• TypeScript 4.7+ (optional)

License

MIT © innerbloo