@kodezen/react-datepicker

A fully custom React date picker component built from scratch — no external date libraries. Supports range selection, single date, dark/light/auto themes, dynamic placements, shortcuts, and full customization via CSS variables.

Inspired by react-advance-datepicker.

Preview

| Light Mode | Dark Mode | |:---:|:---:| | | |

Requirements

| Dependency | Version | |---|---| | Node.js | >= 14.x (recommended >= 18.x) | | React | ^16.8.0 \|\| ^17.0.0 \|\| ^18.0.0 | | react-dom | ^16.8.0 \|\| ^17.0.0 \|\| ^18.0.0 |

Note: React and react-dom are peer dependencies and must be installed in your project separately.

Installation

npm install @kodezen/react-datepicker

Basic Usage

import React, { useState } from 'react';
import DatePicker from '@kodezen/react-datepicker';
// No CSS import needed — styles are injected automatically!

const App = () => {
  const [date, setDate] = useState(null);

  return (
    <DatePicker
      value={date}
      onChange={(newDate) => setDate(newDate)}
    />
  );
};

export default App;

Props

| Prop | Type | Default | Description | |---|---|---|---| | value | { startDate, endDate } \| null | null | The selected date value. Each date can be a Date object or date string. | | onChange | (value, e?) => void | — | Required. Callback fired when the user selects a date. | | asSingle | boolean | false | If true, only allows picking a single date instead of a range. | | useRange | boolean | true | If false, hides the second calendar and disables range selection. | | placeholder | string | — | Input placeholder text. | | displayFormat | string | "YYYY-MM-DD" | Format string for how dates are displayed in the input. | | separator | string | "~" | String used to separate start and end dates in the input. | | startFrom | Date \| string \| null | null | The date the calendar should open to initially. | | minDate | Date \| string \| null | null | Minimum selectable date. | | maxDate | Date \| string \| null | null | Maximum selectable date. | | disabledDates | Array<{ start, end }> \| null | null | Array of date ranges to disable. | | disabled | boolean | false | Disables the entire input. | | readOnly | boolean | false | Makes the text input read-only (calendar still opens). | | theme | "auto" \| "light" \| "dark" | "auto" | Color theme. "auto" follows the OS system preference. | | placement | "bottom" \| "top" \| "left" \| "right" \| "auto" | "bottom" | Where the calendar popup opens relative to the input. "auto" picks the best position based on available screen space. | | showShortcuts | boolean | false | Show quick date shortcut buttons (e.g., Today, Last 7 days). | | showFooter | boolean | false | Show Apply/Cancel footer buttons. | | shortcutText | string \| null | null | Prefix label shown inside the input on the left side. | | primaryColor | string | "blue" | Primary accent color for the datepicker. | | i18n | string | "en" | Locale string for internationalization. | | startWeekOn | "sun" \| "mon" | "sun" | Day the week starts on. | | dateLooking | "forward" \| "backward" \| "middle" | "forward" | Controls how incomplete ranges are displayed. | | inputId | string | — | id attribute for the input element. | | inputName | string | — | name attribute for the input element. | | inputClassName | string \| (cls: string) => string | — | Custom class(es) for the input element. | | containerClassName | string \| (cls: string) => string | — | Custom class(es) for the outer container. | | toggleClassName | string \| (cls: string) => string | — | Custom class(es) for the calendar toggle button. | | toggleIcon | (open: boolean) => ReactNode | — | Custom icon component for the toggle button. | | classNames | Object | — | Fine-grained class overrides for sub-components. | | configs | Object | — | Advanced configuration options for shortcuts. | | suffix | string | "" | Suffix appended to all internal CSS class names (useful for multiple instances). | | popoverDirection | string | — | Legacy popover direction override. Prefer placement instead. |

Styling & Customization

The datepicker uses CSS Custom Properties (variables) for theming — no !important needed.

CSS Variables

Override these in your :root or a parent selector:

:root {
  --kz-datepicker-primary: #3b82f6;       /* Accent / primary color */
  --kz-datepicker-bg: #ffffff;            /* Background color */
  --kz-datepicker-text: #374151;          /* Text color */
  --kz-datepicker-border: #d1d5db;        /* Border color */
  --kz-datepicker-border-radius: 4px;     /* Border radius */
  --kz-datepicker-font-family: inherit;   /* Font family */
  --kz-datepicker-hover-bg: #f3f4f6;     /* Hover background */
}

Class Prop Overrides

Use these props to inject custom classes into different parts:

| Prop | Targets | |---|---| | containerClassName | Outer wrapper <div> | | inputClassName | The text <input> | | toggleClassName | Calendar toggle <button> | | dayClassName (via classNames) | Individual day cells | | calendarClassName (via classNames) | Calendar popover container |

Theme Examples

// Follow OS preference (default)
<DatePicker value={date} onChange={setDate} theme="auto" />

// Always light
<DatePicker value={date} onChange={setDate} theme="light" />

// Always dark
<DatePicker value={date} onChange={setDate} theme="dark" />

Placement Examples

// Opens below (default)
<DatePicker value={date} onChange={setDate} placement="bottom" />

// Opens above
<DatePicker value={date} onChange={setDate} placement="top" />

// Auto-detect based on available viewport space
<DatePicker value={date} onChange={setDate} placement="auto" />

License

ISC