ThekDatePicker

Framework-agnostic date/time picker with strict mask typing, flexible separators, and themed UI.

Quick Docs

NPM / ESM

Use this in modern bundlers like Vite, Webpack, or Nuxt.

npm install
npm run dev

import { createDatePicker, setGlobalOptions } from 'thekdatepicker';
import 'thekdatepicker/css/base.css';

setGlobalOptions({
  format: 'YYYY-MM-DD',
  theme: 'auto',
  reactiveTheme: true,
  themeAttribute: 'data-showcase-theme',
  useLocaleDefaults: true,
  locale: 'en-US'
});

createDatePicker('#my-date', {
  enableTime: true,
  timeFormat: 'hh:mm A'
});

Browser CDN

Use this directly in plain HTML without a build step.

<link rel="stylesheet" href="https://unpkg.com/thekdatepicker/dist/css/base.css">
<input id="my-date" type="text">
<script src="https://unpkg.com/thekdatepicker/dist/thekdatepicker.umd.cjs"></script>
<script>
  ThekDatePicker.setGlobalOptions({
    theme: 'auto',
    reactiveTheme: true,
    themeAttribute: 'data-theme'
  });
  ThekDatePicker.createDatePicker('#my-date');
</script>

Theme Usage

Use a template or pass a theme token object per instance.

createDatePicker('#date-a', { theme: 'dark' });

createDatePicker('#date-b', {
  theme: {
    primary: '#e11d48',
    bgSurface: '#fff1f2',
    border: '#fecdd3'
  }
});

setGlobalOptions({
  format: 'YYYY-MM-DD',
  theme: 'light'
});

Basic Date

Date

createDatePicker('#basic-input', {
  format: 'DD/MM/YYYY',
  defaultDate: new Date()
});

Date Time (24h)

Date + Time (24h)

createDatePicker('#datetime24-input', {
  format: 'YYYY-MM-DD',
  enableTime: true,
  timeFormat: 'HH:mm',
  defaultDate: new Date()
});

Date Time (12h AM/PM)

Date + Time (12h)

createDatePicker('#datetime12-input', {
  format: 'MM/DD/YYYY',
  enableTime: true,
  timeFormat: 'hh:mm A',
  defaultDate: new Date()
});

Date + Time (12h lowercase)

createDatePicker('#datetime12-lower-input', {
  format: 'DD.MM.YYYY',
  enableTime: true,
  timeFormat: 'hh:mm a',
  defaultDate: new Date()
});

Behavior Variants

Open on input click

createDatePicker('#open-on-click-input', {
  format: 'DD/MM/YYYY',
  openOnInputClick: true
});

No calendar button

createDatePicker('#no-button-input', {
  format: 'YYYY/MM/DD',
  showCalendarButton: false
});

Constraints

Min/Max

createDatePicker('#range-input', {
  format: 'MM/DD/YYYY',
  minDate: '2026-01-10',
  maxDate: '2026-12-20'
});

Week starts on Monday

createDatePicker('#monday-start-input', {
  format: 'DD/MM/YYYY',
  weekStartsOn: 1
});

Suspicious Date Warning

createDatePicker('#suspicious-input', {
  format: 'YYYY-MM-DD',
  suspiciousWarning: true,
  suspiciousYearSpan: 100,
  suspiciousMinYear: 1900,
  suspiciousMaxYear: 2100
});

Events

Event callbacks demo

This demo logs `onOpen`, `onChange`, and `onClose` as they happen.

Event Log

createDatePicker('#events-input', {
  format: 'DD/MM/YYYY',
  onOpen: () => log('onOpen'),
  onChange: (date, formatted) => log(`onChange: ${formatted}`),
  onClose: () => log('onClose')
});

API Methods

`open()` shows the popover, `close()` hides it, `setDate(new Date())` sets current date/time, and `clear()` resets value.

const apiPicker = createDatePicker('#api-target', {
  format: 'DD/MM/YYYY HH:mm',
  enableTime: true
});

apiPicker.open();
apiPicker.setDate(new Date());
apiPicker.clear();

Theme Configurator

Template Primary Primary Strong Primary Contrast Surface Panel Border Text Main Text Muted Shadow Font Family Radius Control Height

Live Preview

API Reference Tables

Config Options

Property	Type	Default	Description
format	string	DD/MM/YYYY	Date mask/parse/display format.
locale	string	system locale	Locale used for deriving defaults.
useLocaleDefaults	boolean	false	Derives format/time/week-start from locale unless explicitly set.
enableTime	boolean	false	Controls visibility of popover time inputs.
timeFormat	string	HH:mm	Used only when `format` has no time tokens and `enableTime` is true.
minDate / maxDate	Date \| string \| number	undefined	Selection bounds.
defaultDate	Date \| string \| number	undefined	Initial value.
placeholder	string	derived	Input placeholder override.
disabled	boolean	false	Disables interaction.
appendTo	HTMLElement	document.body	Popover mount target.
weekStartsOn	0..6	0	First weekday.
closeOnSelect	boolean	true	Close after date click in date-only mode.
showCalendarButton	boolean	true	Renders trigger button.
openOnInputClick	boolean	false	Open on input click.
theme	'light' \| 'dark' \| 'auto' \| Partial<ThekDatePickerTheme>	{}	Per-instance template or token overrides from JavaScript.
reactiveTheme	boolean	false	When true and `theme: 'auto'`, follows page theme changes.
themeAttribute	string	data-theme	Document attribute used to detect `light`/`dark` page theme.
suspiciousWarning	boolean	false	Enables suspicious-date warning indicator.
suspiciousYearSpan	number	100	Warns when year is outside current year ± span.
suspiciousMinYear	number	undefined	Optional absolute lower year bound for warning.
suspiciousMaxYear	number	undefined	Optional absolute upper year bound for warning.
suspiciousMessage	string	Suspicious date value	Tooltip text for warning state.
revertWarning	boolean	true	Shows sticky `!` pill; tooltip includes rejected user input until corrected/null commit.
revertMessage	string	Invalid input value	Tooltip text for revert indicator state.

Instance Properties

Property	Type	Default	Description
input	HTMLInputElement	set at init	Target input element.
options	ResolvedOptions	resolved	Runtime config with defaults applied.

Functions / Methods

Function	Type	Default	Description
createDatePicker(target, options?)	factory	n/a	Creates and returns a new ThekDatePicker instance.
setGlobalOptions(options)	global function	n/a	Sets and merges global defaults for new instances.
getGlobalOptions()	global function	n/a	Returns current global defaults.
resetGlobalOptions()	global function	n/a	Clears global defaults back to library defaults.
open()	instance method	n/a	Opens the datepicker popover.
close()	instance method	n/a	Closes the datepicker popover.
toggle()	instance method	n/a	Toggles popover open/close state.
setDate(value, triggerChange?)	instance method	triggerChange=true	Parses and sets date value; clamps against min/max.
getDate()	instance method	n/a	Returns selected date or null.
clear(triggerChange?)	instance method	triggerChange=true	Clears current value and input display.
setMinDate(value)	instance method	n/a	Updates minimum selectable date.
setMaxDate(value)	instance method	n/a	Updates maximum selectable date.
setDisabled(disabled)	instance method	n/a	Enables or disables interaction.
setTheme(theme)	instance method	n/a	Applies template (`light`/`dark`/`auto`) or theme token object at runtime.
destroy()	instance method	n/a	Removes listeners and DOM bindings.
formatDate(date, format)	utility function	n/a	Formats a Date by ThekDatePicker tokens.
parseDateByFormat(value, format)	utility function	n/a	Parses text strictly with token format.
applyMaskToInput(value, format)	utility function	n/a	Applies typing mask and separators to input text.

Events

Event	Type	Default	Description
onOpen	(instance) => void	undefined	Fires when popover opens.
onChange	(date, formatted, instance) => void	undefined	Fires when selected value changes.
onClose	(instance) => void	undefined	Fires when popover closes.

Theme Tokens

Token	Type	Default	Description
primary	string	system accent	Main accent color.
primaryStrong	string	accent mix	Stronger accent for active states.
primaryContrast	string	system accent text	Text color on accent surfaces.
bgSurface	string	system canvas	Input and popover base background.
bgPanel	string	system canvas mix	Subtle panel and hover background.
border	string	system border mix	Borders for controls and popover.
textMain	string	system canvas text	Primary text color.
textMuted	string	system muted mix	Secondary text color.
shadow	string	token shadow	Popover box-shadow.
radius	string	0.375rem	Corner radius for controls.
fontFamily	string	inherit	Font family for component text.
controlHeight	string	2rem	Input and button height.

Default Init (All Defaults Explicit)

createDatePicker('#my-date', {
  format: 'DD/MM/YYYY',
  locale: undefined,
  useLocaleDefaults: false,
  enableTime: false,
  timeFormat: 'HH:mm',
  minDate: undefined,
  maxDate: undefined,
  defaultDate: undefined,
  placeholder: undefined, // defaults to derived format
  disabled: false,
  appendTo: document.body,
  weekStartsOn: 0,
  closeOnSelect: true,
  showCalendarButton: true,
  openOnInputClick: false,
  theme: {},
  reactiveTheme: false,
  themeAttribute: 'data-theme',
  suspiciousWarning: false,
  suspiciousYearSpan: 100,
  suspiciousMinYear: undefined,
  suspiciousMaxYear: undefined,
  suspiciousMessage: 'Suspicious date value',
  revertWarning: true,
  revertMessage: 'Invalid input value',
  onChange: undefined,
  onOpen: undefined,
  onClose: undefined
});