SuperDate

TypeScript date/time input enhancer. Replaces the native browser date-picker chrome with a fully custom, format-aware overlay — while still delegating the actual popup to the OS so you never re-implement a calendar or clock widget.

Supports input[type="date"], input[type="time"], and input[type="datetime-local"].

Features

Feature	Detail
3 input types	date, time, and datetime-local all supported
Auto-observe	SuperDate.bind('.selector') watches the DOM via MutationObserver — inputs added later are automatically enhanced
Custom format	Global default or per-element via data-date-format, data-time-format, data-date-time-delimiter
Keyboard editing	↑ ↓ step values, ← → move segments, 0–9 type digits, auto-advance on completion
Copy / Paste	Parses pasted text against configured format + common fallbacks
Native picker	Calendar / clock icon opens the OS picker; input.value stays as ISO string
Zero dependencies	Plain TypeScript, no runtime deps

Install

npm install @maihcx/super-date
# or copy dist/ into your project

Build

npm install
npm run build

Outputs:

File	Format
dist/super-date.esm.js	ES Module
dist/super-date.esm.min.js	ES Module (minified)
dist/super-date.umd.js	UMD (browser global SuperDate)
dist/super-date.min.js	UMD (minified)

Usage

Via <script> tag

<link rel="stylesheet" href="dist/super-date.min.css" />
<script src="dist/super-date.umd.js"></script>
<script>
  SuperDate.bind('.sd', { format: 'dd/MM/yyyy' });
</script>

ES Module

import SuperDate from './dist/super-date.esm.js';
SuperDate.bind('.sd', { format: 'dd/MM/yyyy' });

TypeScript / bundler

import SuperDate from 'superdate';
SuperDate.bind('.sd');

API

SuperDate.bind(selector, options?)

Enhances all current and future <input type="date">, <input type="time">, and <input type="datetime-local"> elements matching selector.

SuperDate.bind('.sd', {
  format:            'dd/MM/yyyy', // date display format
  timeFormat:        'HH:mm',      // time display format
  dateTimeDelimiter: ' ',          // separator between date and time parts
  locale:            'vi-VN',      // locale (reserved for future i18n)
});

Returns this for chaining.

SuperDate.init(el, options?)

Manually enhance a single element. Returns the SuperDateInstance.

const el = document.querySelector('#my-input') as HTMLInputElement;
SuperDate.init(el, { format: 'yyyy/MM/dd' });

SuperDate.destroy(el)

Remove the overlay and restore the original native input.

Options

Option	Type	Default	Description
format	string	'dd/MM/yyyy'	Display format for date and the date part of datetime-local inputs
timeFormat	string	'HH:mm'	Display format for time and the time part of datetime-local inputs
dateTimeDelimiter	string	' '	String inserted between date and time parts in datetime-local inputs
locale	string	navigator.language	Locale (reserved)

Per-element overrides (data attributes)

<!-- date -->
<input type="date" data-date-format="yyyy/MM/dd" />

<!-- time -->
<input type="time" data-time-format="HH:mm:ss" />

<!-- datetime-local — all three can be combined -->
<input type="datetime-local"
  data-date-format="dd/MM/yyyy"
  data-time-format="HH:mm:ss"
  data-date-time-delimiter=" | " />

Per-element attributes always take priority over bind() options.

Supported tokens

Date tokens

Token	Description	Example
yyyy	4-digit year	2025
yy	2-digit year	25
MM	Month, zero-padded	03
M	Month, no padding	3
dd	Day, zero-padded	07
d	Day, no padding	7

Time tokens

Token	Description	Example
HH	Hours 24h, zero-padded	09, 23
H	Hours 24h, no padding	9, 23
hh	Hours 12h, zero-padded	09, 11
h	Hours 12h, no padding	9, 11
mm	Minutes, zero-padded	05, 59
ss	Seconds, zero-padded	00, 59

Note: MM = months (uppercase), mm = minutes (lowercase).

CSS variables

Override the overlay appearance per-element or globally:

.superdate-overlay {
  --superdate-active-bg:          #2563eb;  /* active segment background */
  --superdate-active-color:       #fff;     /* active segment text */
  --superdate-placeholder-color:  #9ca3af;  /* empty segment placeholder */
  --superdate-sep-color:          inherit;  /* separator / literal color */
}

Keyboard shortcuts

Key	Action
0–9	Type digit into active segment, auto-advance when full
↑ / ↓	Increment / decrement active segment value
← / →	Move to previous / next segment
Tab / Shift+Tab	Move to next / previous segment
Backspace	Erase last typed digit in buffer
Escape	Deactivate / clear selection
Ctrl+A	Select all segments
Ctrl+C	Copy selected segments as formatted text
Click & drag	Multi-segment selection
Double-click	Select all segments

Input value

The underlying input.value always stays in native ISO format — SuperDate only changes the visual overlay:

Input type	input.value format
date	yyyy-MM-dd
time	HH:mm:ss
datetime-local	yyyy-MM-ddTHH:mm:ss

License

MIT