SuperDate

Lightweight TypeScript enhancer for native date, time, and datetime-local inputs.

SuperDate replaces the native browser date/time picker chrome with a fully custom, format-aware overlay — while still delegating the actual popup calendar or clock to the OS. You never re-implement a calendar widget.

The underlying input.value always stays in standard ISO format, so it drops in alongside any existing form logic without changes.

Install & Build

Copy the dist/ folder into your project, or build from source:

npm install
npm run build

CDN (jsDelivr)

No installation needed — load SuperDate directly via jsDelivr. Use the @latest tag to always receive the newest version automatically:

Always use the latest version ✦ recommended

<!-- CSS -->
<link rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/@maihcx/super-date@latest/dist/super-date.min.css" />

<!-- JS (UMD — exposes global SuperDate) -->
<script src="https://cdn.jsdelivr.net/npm/@maihcx/super-date@latest/dist/super-date.min.js"></script>

Pin a specific version

If you need stricter stability guarantees for production, replace @latest with an exact version number:

<link rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/@maihcx/super-date@1.0.0/dist/super-date.min.css" />
<script src="https://cdn.jsdelivr.net/npm/@maihcx/super-date@1.0.0/dist/super-date.min.js"></script>

ESM via jsDelivr

<script type="module">
  import SuperDate from 'https://cdn.jsdelivr.net/npm/@maihcx/super-date@latest/dist/super-date.esm.min.js';
  SuperDate.bind('.sd', { format: 'dd/MM/yyyy' });
</script>

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');

SuperDate.bind()

Enhances all current and future matching inputs. Uses a MutationObserver to catch inputs added to the DOM after the call.

SuperDate.bind(selector: string, options?: SuperDateOptions): this

Supports input[type="date"], input[type="time"], and input[type="datetime-local"] within the same selector. Returns this for chaining.

// all three types under one selector
SuperDate.bind('.sd', {
  format:            'dd/MM/yyyy',
  timeFormat:        'HH:mm',
  dateTimeDelimiter: ' ',
});

// chaining
SuperDate
  .bind('.date-field', { format: 'yyyy/MM/dd' })
  .bind('.time-field', { timeFormat: 'HH:mm:ss' });

SuperDate.init()

Manually enhance a single element. Returns the SuperDateInstance. Safe to call on an already-enhanced element — returns the existing instance.

SuperDate.init(el: HTMLInputElement, options?: SuperDateOptions): SuperDateInstance

const el = document.querySelector('#my-dt') as HTMLInputElement;
SuperDate.init(el, {
  format:            'dd/MM/yyyy',
  timeFormat:        'HH:mm:ss',
  dateTimeDelimiter: ' | ',
});

SuperDate.destroy()

Removes the overlay, detaches all listeners, and restores the original native input. The element is marked so the MutationObserver won't re-bind it automatically. Call bind() or init() again to re-enable.

SuperDate.destroy(el: HTMLInputElement): void

Options

Format tokens

Date tokens

Time tokens

Data attributes

Per-element attributes always override the global bind() options.

<input type="date"           data-date-format="yyyy/MM/dd" />
<input type="time"           data-time-format="HH:mm:ss" />
<input type="datetime-local"
       data-date-format="dd/MM/yyyy"
       data-time-format="HH:mm:ss"
       data-date-time-delimiter=" | " />

CSS variables

Scope overrides to .superdate-overlay on a wrapper or globally:

/* Override globally */
.superdate-overlay {
  --superdate-active-bg:         #0ea5e9;
  --superdate-active-color:      #fff;
  --superdate-placeholder-color: #475569;
  --superdate-sep-color:         #64748b;
}

/* Or scope to one wrapper */
#my-form .superdate-overlay {
  --superdate-active-bg: #7c3aed;
}

Keyboard shortcuts

Input value

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

Live demo — date

Live demo — time

Live demo — datetime-local