z-cal

    Installation

    Documentation index

    npm and bundlers

    npm install z-cal

    For React, install compatible peers if needed:

    npm install react@^19 react-dom@^19
npm install --save-dev @types/react@^19 @types/react-dom@^19

    The @types packages are for TypeScript applications. There is one published package: import vanilla APIs from z-cal and React APIs from z-cal/react. Do not run npm install z-cal/react; it is a subpath export. Solid/Svelte packages in the repository are private placeholders.

    import 'z-cal/polyfill'
import { createCalendar, DayGrid } from 'z-cal'
import 'z-cal/style.css'

export function mountCalendar(host: HTMLElement) {
  return createCalendar(host, { plugins: [DayGrid], options: { view: 'dayGridMonth' } })
}

    The host must exist when createCalendar runs. Call calendar.destroy() on teardown. The React component handles mounting and cleanup; see the quickstart.

    Runtime requirements

    • ESM: use import, with an ESM-aware bundler/runtime. There is no CommonJS require entry.
    • Browser DOM: interactive rendering requires a browser. React server rendering produces an empty host; it mounts the calendar on the client.
    • Temporal: z-cal/polyfill loads the included polyfill only when native Temporal is absent. Keep this import for portability; it uses top-level await, which your bundler must support.
    • CSS: import z-cal/style.css once at your application's stylesheet entry. Importing JavaScript alone does not load the published stylesheet.
    • React: the adapter requires React and React DOM 19. React is optional for vanilla consumers.
    • Node: package metadata declares Node >=22.12. Node is relevant to tooling and SSR, not a substitute for a browser DOM. Repository development uses Node 26 and Bun 1.4.2.

    Styles target modern browsers with CSS nesting, subgrid, oklch(), and light-dark() support. The CSS build targets Chrome 123, Firefox 120, and Safari 17.5; this is a build configuration, not an exhaustive compatibility guarantee. Automated browser coverage uses Chromium and WebKit.

    In server/client frameworks, put the interactive component in a client boundary and follow the framework's rules for global CSS imports. See React server rendering.

    CDN without a bundler

    This complete HTML page uses a pinned release and exposes the global ZCal. The IIFE includes the Temporal polyfill and built-in plugins. Load its companion CSS separately.

    <!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>z-cal example</title>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/z-cal@0.1.0/dist/z-cal.global.css" />
  </head>
  <body>
    <div id="calendar"></div>
    <script src="https://cdn.jsdelivr.net/npm/z-cal@0.1.0/dist/z-cal.global.js"></script>
    <script>
      const calendar = ZCal.createCalendar(document.getElementById('calendar'), {
        plugins: [ZCal.DayGrid, ZCal.TimeGrid, ZCal.Interaction],
        options: { view: 'dayGridMonth', height: '650px', editable: true },
      })
    </script>
  </body>
</html>

    Use the same pinned version for the script and stylesheet. The React adapter is an ESM entry, not part of the ZCal global. See API exports for smaller import paths.