@scopmx/calendar-customization

A turnkey scheduling calendar for React — drop in a full resource-scheduling app or a personal-calendar app, or build your own layout from the same primitives.

Two ready-to-use, full-featured components cover most products out of the box:

• CalendarWorkspace — an all-in-one app: personal calendar and resource-grid ("who's free when") modes behind a single toggle, sharing one events/resources store and one density/theme setting.
• ResourceScheduler — the resource-grid mode alone (rows/columns are people or rooms), for a product that only needs that view.

Both bundle event create/edit, drag-and-drop, a per-resource working-hours editor, and undo toasts — the same experience end to end, not just the grid.

Features

• Views: Day, Week, Fortnight, Month, Agenda/Schedule, and an arbitrary Custom range — both in a resource grid (ResourceScheduler) and an aggregated personal-calendar layout (FullCalendarApp).
• Drag-and-drop, validated live: dragging previews whether the drop is valid (capacity, working hours) before you release — an invalid drop snaps back with a toast instead of committing and asking you to fix it after. Dragging a recurring event prompts this/following/all, matching its own edit dialog; dragging one day of a multi-day event prompts whether to move the whole span or split that day off into its own event.
• Recurring events: weekly rules, per-occurrence exceptions, and this/following/all edit and delete scoping.
• Resource scheduling: per-resource working hours (with date-specific overrides), capacity/double-booking limits, a schedule editor with saveable templates, bulk date overrides (holidays), and copy/paste-week authoring.
• Theming: light/dark/system, three density presets, 14 named event colors, and a CSS-custom-property token system (@scopmx/calendar-customization/tailwind-preset + @scopmx/calendar-customization/styles.css) — restyle without touching component code.
• Responsive: the filter sidebar and secondary toolbar controls collapse below ~900px instead of overflowing.
• Accessibility: aria-live toasts, keyboard shortcuts, outside-click/Escape-dismissing menus.
• Everything is a controlled prop or an overridable slot — resources/events are host-owned arrays, and every rendered piece (event chip, resource header, empty/loading/error state, and more) can be swapped via the slots prop without forking the library.

Install

npm install @scopmx/calendar-customization

/* your global stylesheet, once */
@import "@scopmx/calendar-customization/styles.css";

// tailwind.config.ts
import calendarPreset from "@scopmx/calendar-customization/tailwind-preset";

export default {
  presets: [calendarPreset],
  content: ["./app/**/*.{ts,tsx}", "./node_modules/@scopmx/calendar-customization/dist/**/*.{js,mjs,cjs}"],
};

On Next.js, also add transpilePackages: ["@scopmx/calendar-customization"] to next.config.mjs.

Quick start

"use client";
import { useState } from "react";
import { CalendarWorkspace } from "@scopmx/calendar-customization";
import type { CalendarEvent, CalendarResource } from "@scopmx/calendar-customization/core";

export function App() {
  const [resources, setResources] = useState<CalendarResource[]>(myResources);
  const [events, setEvents] = useState<CalendarEvent[]>(myEvents);

  return (
    <CalendarWorkspace
      resources={resources}
      onResourcesChange={setResources}
      events={events}
      onEventsChange={setEvents}
      brand="My App"
    />
  );
}

That's the whole thing — mode toggle, dialogs, drag-and-drop, schedule editor, theme/density controls, all included. Reach for ResourceScheduler or FullCalendarApp directly if you only need one mode, or the lower-level Calendar/view components if you're building fully custom chrome.

Entry points

| Import | Use it for | | --- | --- | | @scopmx/calendar-customization | Full client API — components, hooks, everything in core. Client-only (bundles hooks); don't import from a Server Component. | | @scopmx/calendar-customization/core | Server-safe subset — types, date math, mutation/validation logic, URL state. Fine in Server Components and on the server. | | @scopmx/calendar-customization/tailwind-preset | Tailwind config preset mapping utility classes to the token system. | | @scopmx/calendar-customization/styles.css | The token CSS (--cal-color-*, --cal-shadow-*, etc.) the components read. |

Learn more

This package lives in a monorepo alongside a demo app that exercises the full feature set — see the repo root README for the demo, and DEVELOPMENT.md for the full local dev / build / test / "consuming this from another app" guide.