ez-date-picker

Production-grade React date picker with modern range UX and developer-first customization.

This documentation app covers every feature with live demos, copy-ready snippets, and a direct comparison against other popular picker packages.

Install

npm

bash

1npm install ez-date-picker

Quick Start

tsx

1import { useState } from "react";
2import { DatePicker } from "ez-date-picker";
3import "ez-date-picker/styles.css";
4
5export default function Example() {
6  const [date, setDate] = useState<Date | null>(null);
7
8  return <DatePicker value={date} onChange={setDate} />;
9}

Feature Coverage

Single-date mode and full range mode in one component
Hover-preview range selection with clear start/end states
Single-month or dual-month panel rendering
Optional range meta panel and optional preset side panel
Built-in default presets + customizable single/range presets
Theme tokens API (colors, radius, shadow, font) for fast white-labeling
Controlled state API with TypeScript-first prop and preset types

Interactive Demos

Each block below is a real working instance of ez-date-picker with focused configuration examples.

Single Date Mode

Controlled input, locale support, min/max bounds, and Monday-based week layout.

Selected: Thu Feb 26 2026

Single Date

tsx

1import { DatePicker } from "ez-date-picker";
2import "ez-date-picker/styles.css";
3
4<DatePicker
5  value={date}
6  onChange={setDate}
7  minDate={new Date(2024, 0, 1)}
8  maxDate={new Date(2030, 11, 31)}
9  startWeekOnMonday
10/>;

Range Mode + Two Months

Hover preview, start/end selection flow, dual-month panel, and hidden spillover days for cleaner focus.

Selected: None to None

Range + Two Months

tsx

1<DatePicker
2  mode="range"
3  rangeValue={range}
4  onRangeChange={setRange}
5  rangeMonthsToShow={2}
6  startWeekOnMonday
7/>;

Preset Side Panel

Enable quick actions with defaults or provide your own presets, labels, and contextual names.

Selected: None to None

Preset Panel

tsx

1const rangePresets = [
2  { id: "last-week", label: "Last Week" },
3  { id: "next-14", label: "Next 14 Days", getRange: ({ today }) => ({
4      start: today,
5      end: new Date(today.getFullYear(), today.getMonth(), today.getDate() + 13)
6  })}
7];
8
9<DatePicker
10  mode="range"
11  showPresetPanel
12  presetPanelTitle="Quick Ranges"
13  rangePresetLabel="Team Presets"
14  rangePresets={rangePresets}
15/>;

Theme Tokens

Pass typed theme tokens for color, radius, font, and elevation. No CSS override hacks needed.

Selected: Thu Feb 26 2026

Theme Customization

tsx

1const theme = {
2  background: "#f4f8f9",
3  surface: "#e6eef0",
4  primary: "#176b87",
5  primaryStrong: "#0f5168",
6  border: "#bdd4db",
7  panelRadius: "20px"
8};
9
10<DatePicker theme={theme} showPresetPanel />;

Props Reference

Detailed behavior, defaults, and ready-to-use snippets for every core prop in DatePicker .

mode

"single" | "range"

Default: "single"

Switches between single-date and date-range picker behaviors.

mode

tsx

1<DatePicker mode="range" />

showRangeMeta

boolean

Default: true

Controls the range meta block (start/end + helper text) in range mode.

showRangeMeta

tsx

1<DatePicker mode="range" showRangeMeta={false} />

rangeMonthsToShow

1 | 2

Default: 1

Shows one or two calendar months in range mode.

rangeMonthsToShow

tsx

1<DatePicker mode="range" rangeMonthsToShow={2} />

theme

Partial<DatePickerTheme>

Default: undefined

Typed theme tokens mapped to CSS variables for fast white-labeling.

theme

tsx

1const theme = { primary: "#176b87", panelRadius: "18px" };
2<DatePicker theme={theme} />

showPresetPanel

boolean

Default: false

Enables side panel with quick date/date-range presets.

showPresetPanel

tsx

1<DatePicker mode="range" showPresetPanel />

presetPanelTitle

string

Default: "Quick Select"

Heading text displayed at the top of the preset panel.

presetPanelTitle

tsx

1<DatePicker showPresetPanel presetPanelTitle="Quick Ranges" />

singlePresetLabel

string

Default: "Single Date"

Subtitle shown in preset panel when `mode="single"`.

singlePresetLabel

tsx

1<DatePicker showPresetPanel singlePresetLabel="Shortcuts" />

rangePresetLabel

string

Default: "Date Range"

Subtitle shown in preset panel when `mode="range"`.

rangePresetLabel

tsx

1<DatePicker mode="range" showPresetPanel rangePresetLabel="Team Presets" />

singlePresets

SingleDatePreset[]

Default: built-in presets

Custom single-date presets. Add/remove items or dynamic resolvers.

singlePresets

tsx

1const singlePresets = [
2  { id: "today", label: "Today" },
3  { id: "next-friday", label: "Next Friday", getDate: ({ today }) => new Date(today.getFullYear(), today.getMonth(), today.getDate() + 5) }
4];
5<DatePicker showPresetPanel singlePresets={singlePresets} />

rangePresets

RangeDatePreset[]

Default: built-in presets

Custom range presets with static `range` or dynamic `getRange`.

rangePresets

tsx

1const rangePresets = [
2  { id: "last-week", label: "Last Week" },
3  { id: "next-14", label: "Next 14 Days", getRange: ({ today }) => ({ start: today, end: new Date(today.getFullYear(), today.getMonth(), today.getDate() + 13) }) }
4];
5<DatePicker mode="range" showPresetPanel rangePresets={rangePresets} />

value

Date | null

Default: null

Controlled selected value for single-date mode.

value

tsx

1<DatePicker value={date} onChange={setDate} />

onChange

(date: Date | null) => void

Default: undefined

Change callback for single-date mode.

onChange

tsx

1<DatePicker value={date} onChange={(next) => setDate(next)} />

rangeValue

DateRange | null

Default: null

Controlled selected range for range mode.

rangeValue

tsx

1<DatePicker mode="range" rangeValue={range} onRangeChange={setRange} />

onRangeChange

(range: DateRange | null) => void

Default: undefined

Change callback for range mode.

onRangeChange

tsx

1<DatePicker mode="range" onRangeChange={(next) => setRange(next ?? { start: null, end: null })} />

placeholder

string

Default: "Select a date"

Placeholder shown when no value/range is selected.

placeholder

tsx

1<DatePicker placeholder="Pick your meeting date" />

minDate

Date

Default: undefined

Disables all dates before this value.

minDate

tsx

1<DatePicker minDate={new Date(2025, 0, 1)} />

maxDate

Date

Default: undefined

Disables all dates after this value.

maxDate

tsx

1<DatePicker maxDate={new Date(2030, 11, 31)} />

disabled

boolean

Default: false

Disables the trigger input and all interactions.

disabled

tsx

1<DatePicker disabled />

className

string

Default: undefined

Adds custom class to the root wrapper.

className

tsx

1<DatePicker className="my-picker" />

style

React.CSSProperties

Default: undefined

Inline style for the root wrapper (can work with theme tokens).

style

tsx

1<DatePicker style={{ width: 340 }} />

locale

string

Default: "en-US"

Locale for month labels and formatted selected values.

locale

tsx

1<DatePicker locale="en-GB" />

startWeekOnMonday

boolean

Default: false

Reorders weekday layout so the calendar starts with Monday.

startWeekOnMonday

tsx

1<DatePicker startWeekOnMonday />

Theme Tokens

theme accepts Partial<DatePickerTheme>. These tokens map directly to picker CSS variables so you can fully reskin the component without fragile CSS overrides.

background

string

Panel and popup base background color.

surface

string

Day-cell surface/background tone.

border

string

Main border color for inputs, panel, and cards.

text

string

Primary text color used across picker UI.

muted

string

Muted text color for placeholders and helper labels.

primary

string

Primary accent color (selected/interactive states).

primaryStrong

string

Stronger primary shade for gradients/pressed accents.

primarySoft

string

Soft primary tint for hover backgrounds and chips.

shadow

string

Popup shadow style (full CSS shadow value).

fontFamily

string

Font stack for picker typography.

inputRadius

string

Input trigger border radius (e.g. "12px").

panelRadius

string

Calendar panel border radius.

dayRadius

string

Day-cell border radius.

Full Theme Example

tsx

1const theme = {
2  background: "#f4f8f9",
3  surface: "#e6eef0",
4  border: "#bdd4db",
5  text: "#0f172a",
6  muted: "#4b657a",
7  primary: "#176b87",
8  primaryStrong: "#0f5168",
9  primarySoft: "#dbe9ed",
10  shadow: "0 20px 40px rgba(20, 84, 106, 0.18)",
11  fontFamily: ""Manrope", "Segoe UI", sans-serif",
12  inputRadius: "14px",
13  panelRadius: "20px",
14  dayRadius: "12px"
15};
16
17<DatePicker theme={theme} />

Package Comparison

High-level comparison against commonly used React date picker libraries (snapshot: February 24, 2026).

Package	Primary Focus	Strength	Tradeoff
ez-date-picker	Product-ready date + range picker	Preset side panel, theme tokens, range UX, two-month mode	Narrow scope (date-focused)
react-datepicker	Classic all-in-one picker	Mature ecosystem, familiar API, broad adoption	Heavier customization via CSS overrides
react-day-picker	Headless calendar building block	Maximum composability and accessibility control	You build most UX shell yourself
MUI X Date Pickers	Enterprise design-system integration	Deep Material UI integration and broad date/time components	Best fit when you already use MUI
react-date-range	Range-heavy interactions	Strong range-selection UX patterns	Project maintenance cadence has slowed

Contribute & Report Issues

Found a bug, have a feature request, or want to contribute improvements? Use the official GitHub repository:

https://github.com/MdShafiul/ez-date-picker