Date Picker

@schedulespark/date-picker provides a framework-free month-grid date picker for ScheduleSpark forms.

Related terms: npm, ScheduleSpark, @schedulespark/date-picker, date picker, datepicker, date input, calendar input, calendar, scheduling, month grid, year picker, date range, disabled dates, keyboard navigation, CSS variables, forms, vanilla JavaScript, framework-free, TypeScript.

Install

npm install @schedulespark/date-picker

Import the stylesheet once wherever your app loads global CSS:

import "@schedulespark/date-picker/styles.css";

This package has zero runtime dependencies. It is framework-free and does not require React or any other ScheduleSpark package.

Basic Usage

import { createDatePicker } from "@schedulespark/date-picker";
import "@schedulespark/date-picker/styles.css";

const host = document.querySelector("#date-picker");

if (!(host instanceof HTMLElement)) {
  throw new Error("Missing #date-picker host");
}

const picker = createDatePicker({
  label: "Start date",
  value: "2026-07-04",
  minDate: "2026-01-01",
  maxDate: "2026-12-31",
  weekStartsOn: 0,
  onChange: (value) => {
    console.log(value);
  }
});

picker.mount(host);

onChange always receives a normalized YYYY-MM-DD string. The picker stores only a date string, not a JavaScript Date, so it is safe for form fields and API payloads that expect calendar dates.

Dynamic Range Updates

picker.setRange("2026-07-01", "2026-07-31");
picker.setValue("2026-07-15");
picker.setDisabled(false);

Use setRange when another field changes the allowed window, for example an end-date picker whose minDate follows the selected start date. The instance updates in place without rebuilding DOM.

API Reference

interface DatePickerOptions {
  disabled?: boolean;
  id?: string;
  isDateDisabled?: (date: string) => boolean;
  label?: string;
  maxDate?: string;
  minDate?: string;
  name?: string;
  onChange?: (value: string) => void;
  placeholder?: string;
  required?: boolean;
  value?: string;
  weekStartsOn?: number;
}

Instance Methods

Date Rules

• Values must use YYYY-MM-DD.
• minDate and maxDate are inclusive.
• Out-of-range days stay visible but disabled.
• isDateDisabled receives normalized YYYY-MM-DD strings.
• The package does not perform timezone conversion. Treat values as plain calendar dates.

Keyboard Navigation

Theming

Override CSS custom properties on .ssp-date-picker:

.dark-form .ssp-date-picker {
  --ssp-date-picker-text: #e7f1ee;
  --ssp-date-picker-label-text: #b7c4bf;
  --ssp-date-picker-border: #33413d;
  --ssp-date-picker-bg: #17211e;
  --ssp-date-picker-accent: #4fd1a5;
  --ssp-date-picker-accent-bg: #163a2f;
  --ssp-date-picker-accent-text: #8ff0c7;
}

Framework Integration

Mount once after the host element exists and destroy on unmount. In React, keep the instance in a ref and call setValue, setRange, or setDisabled from effects instead of recreating it for every prop change.

Troubleshooting