@reactzero/datepicker

Zero-dependency, accessible React date & time picker.
WCAG 2.1 AA • 7 components • 4 headless hooks • ~12 kB gzipped.

---

Live Demo & Docs • Interactive Storybook • GitHub

---

Why?

Every React datepicker I tried either pulled in a heavy date library (date-fns, moment, dayjs), made styling painful, or both. I wanted something that:

• Has zero runtime dependencies — just native Intl and Date APIs
• Is easy to customize — override a few CSS variables and you're done
• Ships accessible out of the box — WCAG 2.1 AA, keyboard nav, screen readers
• Stays small — under 12 kB gzipped

I couldn't find it, so I built it. @reactzero/datepicker is the first package in the @reactzero family — a collection of zero-dependency React UI primitives that are tiny, accessible, and effortless to style.

Features

• Zero Dependencies — Uses native Intl and Date APIs. No date-fns, moment, or dayjs.
• Micro Bundle — ~12 kB gzipped JS + ~4 kB CSS. Tree-shakeable named exports.
• Accessible (WCAG 2.1 AA) — ARIA grid dialogs, spinbuttons, keyboard navigation, focus management.
• Headless + Styled — Use the styled components or go fully headless with hooks.
• Themeable — 10 built-in themes + 3 density modes via CSS custom properties.
• i18n — Locale-aware formatting, RTL support, configurable first day of week.

Bundle Size

Import	Gzipped
Full bundle (all components)	~8 kB
Single component (DatePicker)	~6 kB
Headless hook (useDatePicker)	~3 kB
CSS (styles)	~4 kB

Sizes are approximate and measured with size-limit.

Installation

npm install @reactzero/datepicker

Quick Start

import { DatePicker } from '@reactzero/datepicker';
import '@reactzero/datepicker/styles';

export default function App() {
  const [date, setDate] = useState<Date | null>(null);

  return (
    <DatePicker
      value={date}
      onChange={setDate}
      placeholder="Select date..."
    />
  );
}

Headless API

For total control over the UI, use the headless hooks — no CSS required:

import { useDatePicker } from '@reactzero/datepicker';

function CustomDatePicker() {
  const {
    state,
    isOpen,
    toggle,
    getContainerProps,
    getTriggerProps,
    getDialogProps,
    getGridProps,
    getCellProps,
  } = useDatePicker({ locale: 'en-US' });

  // Build your own UI with full ARIA compliance...
}

Available hooks:

• useDatePicker — Calendar state, open/close, ARIA prop getters
• useTimePicker — Hour/minute/second spinbuttons, AM/PM toggle
• useRangePicker — Start/end date selection with hover preview
• useCalendarState — Low-level calendar grid state machine

Components

Component	Description
DatePicker	Full date picker with popover calendar
TimePicker	Time selection (inline or popover mode)
DateRangePicker	Two-month range picker with presets
DateTimePicker	Combined date + time picker
CalendarGrid	Presentational calendar grid
FieldWrapper	Accessible form field with label, hint, error
TimeInput	Compact inline time entry with spinbuttons

Styling & Theming

Import the stylesheet and override CSS custom properties:

import '@reactzero/datepicker/styles';

:root {
  --dp-accent: #3b82f6;
  --dp-bg: #ffffff;
  --dp-text: #0f172a;
  --dp-cell-size: 2.5rem;
}

Built-in Themes

Apply a theme via the theme prop or the data-dp-theme attribute:

<DatePicker theme="dark" />
<DatePicker theme="ocean" />
<DatePicker theme="rose" />

Available: light (default), dark, minimal, ocean, rose, purple, amber, slate, glass, hc (high contrast).

Density Modes

<DatePicker density="compact" />
<DatePicker density="comfortable" />

Trigger Styles

Control the trigger appearance with the triggerStyle prop:

<DatePicker triggerStyle="default" />   // Full input + icon (default)
<DatePicker triggerStyle="icon" />      // Circular icon-only button
<DatePicker triggerStyle="minimal" />   // Underline only, no box
<DatePicker triggerStyle="pill" />      // Rounded, accent-filled
<DatePicker triggerStyle="ghost" />     // Transparent, border on hover

AI Reference

Building with AI? Download the ai-reference.md — a comprehensive single-file reference covering every component, hook, prop, CSS variable, and usage pattern. Feed it to your AI coding tool for accurate @reactzero/datepicker code generation.

Browser Support

Targets ES2020. Supports all browsers that support React 18:

• Chrome/Edge 80+
• Firefox 80+
• Safari 14.1+

Documentation

• Live Demo & Docs
• Interactive Storybook
• AI Reference — complete API reference for AI-assisted development
• Run npm run storybook for local component demos

Development

npm install          # Install dependencies
npm run dev          # Start Storybook dev server
npm run build        # Build library (ESM + CJS + types + CSS)
npm run test         # Run unit tests
npm run test:a11y    # Run accessibility tests
npm run size         # Check bundle size
npm run ci           # Full CI pipeline (typecheck + lint + test)

Publishing

Publishing is automated via GitHub Actions. To release a new version:

npm version patch    # or minor / major
git push --tags

The CI workflow runs tests, builds the package, and publishes to npm on version tags. Requires an NPM_TOKEN secret in your GitHub repository settings.

License

MIT - see the LICENSE file for details.

---

Built by motiondesignlv
_GitHub