EssealDatePicker

A lightweight, dependency-free date picker for vanilla JavaScript, React, Vue, Angular, and any other framework.

Full documentation and live demo →

---

Features

• Zero dependencies — pure JavaScript, no external libraries
• Framework agnostic — works with React, Vue, Angular, Svelte, or plain HTML
• React-safe — properly triggers React's synthetic event system
• ~8KB minified — nothing you don't need
• Single date & date range — both modes supported out of the box
• Confirm / Cancel actions — optional in-popup action buttons for controlled confirmation flows
• Customisable — colours, format, locale, z-index
• Accessible — ARIA roles and keyboard-friendly
• Localised — automatic locale detection with full Intl support

---

Installation

npm install esseal-date-picker

CDN (ES module):

<script type="module">
  import EssealDatePicker from "https://cdn.jsdelivr.net/npm/esseal-date-picker/index.js";
</script>

---

Quick Start

Vanilla JavaScript

<input type="text" id="date-picker" placeholder="Select a date" readonly />

<script type="module">
  import EssealDatePicker from "esseal-date-picker";

  new EssealDatePicker("#date-picker", {
    onChange(date) {
      console.log("Selected:", date);
    },
  });
</script>

React

import { useEffect, useRef } from "react";
import EssealDatePicker from "esseal-date-picker";

function DatePickerField() {
  const inputRef = useRef(null);

  useEffect(() => {
    const picker = new EssealDatePicker(inputRef.current, {
      primaryColor: "#3b82f6",
      onChange(date) {
        console.log("Selected:", date);
      },
    });

    return () => picker.destroy();
  }, []);

  return <input ref={inputRef} type="text" placeholder="Select a date" readOnly />;
}

Vue 3

<template>
  <input ref="dateInput" type="text" placeholder="Select a date" readonly />
</template>

<script setup>
import { ref, onMounted, onUnmounted } from "vue";
import EssealDatePicker from "esseal-date-picker";

const dateInput = ref(null);
let picker;

onMounted(() => {
  picker = new EssealDatePicker(dateInput.value, {
    onChange(date) {
      console.log("Selected:", date);
    },
  });
});

onUnmounted(() => picker?.destroy());
</script>

Angular

import { Component, ElementRef, ViewChild, OnInit, OnDestroy } from "@angular/core";
import EssealDatePicker from "esseal-date-picker";

@Component({
  selector: "app-date-picker",
  template: `<input #dateInput type="text" placeholder="Select a date" readonly />`,
})
export class DatePickerComponent implements OnInit, OnDestroy {
  @ViewChild("dateInput", { static: true }) dateInput!: ElementRef;
  private picker: any;

  ngOnInit() {
    this.picker = new EssealDatePicker(this.dateInput.nativeElement, {
      onChange(date: Date) {
        console.log("Selected:", date);
      },
    });
  }

  ngOnDestroy() {
    this.picker?.destroy();
  }
}

---

API Reference

Constructor

new EssealDatePicker(target, options);

Parameter	Type	Description
target	string | HTMLInputElement	CSS selector string or a DOM element
options	object	Configuration — see below

Options

Option	Type	Default	Description
mode	'single' | 'range'	'single'	Single date or date range selection
showActions	boolean	false	Adds Confirm and Cancel buttons inside the popup. Selection is not committed until Confirm is clicked.
locale	string	navigator.language	Locale for month/day labels (e.g. 'en-US', 'fr-FR')
format	function	date.toLocaleDateString('en-CA')	Custom formatter (date: Date) => string
primaryColor	string	'#3b82f6'	Accent colour — must be hex (#RRGGBB or #RGB)
textColor	string	'#1f2937'	Calendar text colour
minDate	Date | string | null	null	Earliest selectable date
maxDate	Date | string | null	null	Latest selectable date
zIndex	number	9999	CSS z-index of the popup
onChange	function | null	null	Called when a date (or range) is committed. Receives a Date in single mode, or { start: Date, end: Date } in range mode. With showActions, this fires on Confirm — not on date click.

Methods

Method	Description
open()	Opens the calendar popup
close()	Closes the calendar popup
destroy()	Removes the popup DOM and all event listeners. Always call this on unmount in React, Vue, and Angular.

---

Usage Examples

Date Range Selection

new EssealDatePicker("#date-range", {
  mode: "range",
  onChange(range) {
    console.log("Start:", range.start);
    console.log("End:", range.end);
  },
});

Confirm / Cancel Actions

Adds Confirm and Cancel buttons inside the popup. The onChange callback fires only when the user clicks Confirm, not on every date click.

new EssealDatePicker("#date-picker", {
  showActions: true,
  onChange(date) {
    console.log("Confirmed:", date);
  },
});

Works with range mode too:

new EssealDatePicker("#date-range", {
  mode: "range",
  showActions: true,
  onChange(range) {
    console.log("Confirmed:", range.start, "→", range.end);
  },
});

Restrict Selectable Dates

new EssealDatePicker("#date-picker", {
  minDate: new Date(2024, 0, 1),   // Jan 1 2024
  maxDate: new Date(2024, 11, 31), // Dec 31 2024
});

Custom Colour Theme

new EssealDatePicker("#date-picker", {
  primaryColor: "#10b981", // green
  textColor: "#374151",
});

Custom Date Format

new EssealDatePicker("#date-picker", {
  format(date) {
    const d = String(date.getDate()).padStart(2, "0");
    const m = String(date.getMonth() + 1).padStart(2, "0");
    return `${d}/${m}/${date.getFullYear()}`; // DD/MM/YYYY
  },
});

Localised Calendar

new EssealDatePicker("#date-picker", {
  locale: "fr-FR",
  format: (date) => date.toLocaleDateString("fr-FR"),
});

Programmatic Control

const picker = new EssealDatePicker("#date-picker");

document.querySelector("#open-btn").addEventListener("click", () => picker.open());
document.querySelector("#close-btn").addEventListener("click", () => picker.close());

Multiple Pickers

Each instance is fully independent:

const start = new EssealDatePicker("#start-date", { primaryColor: "#3b82f6" });
const end   = new EssealDatePicker("#end-date",   { primaryColor: "#ef4444" });

---

Important Notes

primaryColor must be hex

The range in-between highlight is computed by appending an alpha suffix (#3b82f620), so RGB and HSL strings will break it.

// ✅ Valid
primaryColor: "#3b82f6"
primaryColor: "#f00"

// ❌ Invalid
primaryColor: "rgb(59, 130, 246)"
primaryColor: "hsl(217, 91%, 60%)"

Always call destroy() in framework components

// React
useEffect(() => {
  const picker = new EssealDatePicker(ref.current, options);
  return () => picker.destroy();
}, []);

Use readonly on the input

Prevents manual typing while still allowing the picker to update the value:

<input type="text" id="date-picker" readonly />

---

Browser Support

Chrome, Firefox, Safari, and Edge (latest versions). IE11 is not supported.

---

License

MIT — free for personal and commercial use.

---

Part of the Esseal product suite · View product page