🗓️ Extended DateTimePicker

A jQuery date and time picker styled with Bootstrap 5. Use it as an input dropdown or an always-visible inline control, with single dates, ranges, multiple dates, or birthdays.

🎮 Playground · 📦 npm · 💻 GitHub · 🐛 Report an issue · 📝 Changelog

See the changelog for the changes included in each version.

🧭 Contents

• Features
• Installation
• Selection modes
• Dates, times, and restrictions
• Options reference
• Callbacks and form events
• Public methods
• Languages
• Keyboard and layout
• Local development
• Troubleshooting

✨ Features

• 📅 Four selection modes: single date, range, multiple dates, and birthday.
• 🕒 Optional clock: 12-hour or 24-hour display, with separate start/end times for ranges.
• 🚫 Date restrictions: minimum/maximum dates, blocked dates, and disabled weekends.
• 📐 Responsive layouts: vertical or horizontal, with optional two-month calendars.
• 🌍 Spanish and English: built-in dictionaries, custom labels, and translated accessible controls.
• ⌨️ Form integration: keyboard navigation, selection callbacks, and native input/change events.

📦 Installation

Requirements

The picker needs jQuery and Bootstrap CSS, plus its own JavaScript and CSS. Bootstrap JavaScript is not required by the picker itself.

The package declares jQuery >=3.0.0 and Bootstrap >=5.0.0 as peer dependencies. Use Bootstrap 5.3.8 for the theme utilities used by the current demo. A clean consumer installation was verified with jQuery 3.7.1 + Bootstrap 5.3.8.

With npm and a bundler

npm install jquery-extended-datetimepicker jquery bootstrap

Add a target to your page:

<label for="my-datepicker">Choose a date</label>
<input id="my-datepicker" type="text" class="form-control" />

Import the plugin and both stylesheets in your JavaScript entry point:

import $ from "jquery";
import "bootstrap/dist/css/bootstrap.min.css";
import "jquery-extended-datetimepicker";
import "jquery-extended-datetimepicker/dist/jquery.extended.datetimepicker.min.css";

$(function () {
  $("#my-datepicker").extendedDateTimePicker({
    lang: "en",
    showClock: false,
  });
});

The package entry is ESM. It imports jQuery from your project; there is no need to create a global $ for this setup.

With browser script tags / CDN

Load jQuery before the plugin. This example pins version 1.5.3; use the release you want to deploy.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Date picker example</title>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" />
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/jquery.extended.datetimepicker.min.css" />
  </head>
  <body>
    <label for="my-datepicker">Choose a date</label>
    <input id="my-datepicker" type="text" class="form-control" />
    <script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/jquery.extended.datetimepicker.min.js"></script>
    <script>
      $("#my-datepicker").extendedDateTimePicker({ lang: "en", showClock: false });
    </script>
  </body>
</html>

For self-hosted files, replace the plugin CDN URLs with paths to the files in dist/. Do not load the ESM file as a classic browser script.

🎛️ Selection modes

| Mode | Use it for | Initial selection | | --- | --- | --- | | single | One appointment or date | One ISO date | | range | A start and end date | Up to two ISO dates | | multiple | Separate dates | An array of ISO dates | | birthday | Day, month, and year controls | One ISO date, year 1900 through the current year |

📅 Single date

$("#my-datepicker").extendedDateTimePicker({
  mode: "single",
  lang: "en",
  showClock: false,
  selectedDates: ["2026-10-15"],
  dateFormat: "DD/MM/YYYY",
});
// Input: 15/10/2026

↔️ Range with individual times

$("#range-picker").extendedDateTimePicker({
  mode: "range",
  lang: "en",
  doubleMonth: true,
  selectedDates: ["2026-10-15", "2026-10-20"],
  defaultTime: ["09:00", "17:30"],
});
// Input: 2026-10-15 09:00 to 2026-10-20 17:30

🗓️ Multiple dates

$("#multiple-picker").extendedDateTimePicker({
  mode: "multiple",
  showClock: false,
  selectedDates: ["2026-10-15", "2026-10-20", "2026-10-23"],
});

🎂 Birthday

$("#birthday-picker").extendedDateTimePicker({
  mode: "birthday",
  lang: "en",
  showClock: false,
  selectedDates: ["2000-01-01"],
  dateFormat: "DD/MM/YYYY",
});

📌 Inline control

Use a container instead of an input. The same configuration options apply:

<div id="inline-picker"></div>

$("#inline-picker").extendedDateTimePicker({
  showClock: false,
  selectedDates: ["2026-10-15"],
});

An input opens on focus or click. An inline container is visible immediately. Initialization replaces the contents of an inline container; destroying it does not restore those contents.

📅 Dates, times, and restrictions

Input values versus display format

• Always pass dates as YYYY-MM-DD strings, including selectedDates, minDate, maxDate, and disabledDates. Do not pass Date objects to these options.
• dateFormat changes the displayed output, not the format of configuration values. Supported tokens are YYYY, YY, MM, M, DD, and D.
• Pass defaultTime in 24-hour HH:mm format, even when format24h is false. A range accepts either one time for both ends or an array of two times.
• Without defaultTime, the clock starts at 06:00 for single/multiple/birthday modes, or 00:00 and 23:59 for a range. Invalid time strings use those defaults.
• Date objects returned by callbacks represent local dates, not UTC timestamps.

Restrict selectable dates

$("#my-datepicker").extendedDateTimePicker({
  minDate: "2026-10-01",
  maxDate: "2026-10-31",
  disableWeekends: true,
  disabledDates: ["2026-10-12"],
  showClock: false,
});

Restrictions apply to initial selections, calendar clicks, birthdays, and Today. Invalid or blocked initial dates are ignored. For ranges, restrictions apply to the endpoints; blocked dates inside a selected range are permitted.

A blocked birthday edit clears the submitted input value until a valid date is selected again. Invalid date limits, reversed limits, unsupported modes, and malformed translations throw before replacing an existing picker.

Use only the clock

$("#time-picker").extendedDateTimePicker({
  showCalendar: false,
  showClock: true,
  format24h: false,
  defaultTime: "14:30",
});
// Input: 02:30 PM

⚙️ Configurable Options Table

| Option | Type | Default | Description / Allowed Values | | --- | --- | --- | --- | | mode | string | 'single' | 'single', 'range', 'multiple', or 'birthday'. | | layout | string | 'vertical' | 'vertical' or 'horizontal'. Horizontal applies when both calendar and clock are visible outside birthday mode. | | showCalendar | boolean | true | Show the calendar; birthday mode uses its own date controls. | | showClock | boolean | true | Show the clock. Set to false for date-only selection. | | themeColor | string | 'success' | Bootstrap color name, such as 'primary', 'success', or 'danger'. | | format24h | boolean | true | Use 24-hour display; false shows 12-hour time with AM/PM. | | defaultTime | string/array/null | null | Initial HH:mm time, or two times for a range. Configuration always uses 24-hour format. | | selectedDates | array | [] | Initial ISO dates. Single/birthday use one; range uses up to two; multiple accepts several. | | minDate | string/null | null | Earliest selectable ISO date, inclusive. | | maxDate | string/null | null | Latest selectable ISO date, inclusive. | | disableWeekends | boolean | false | Disable Saturdays and Sundays. | | disabledDates | array | [] | Specific ISO dates that cannot be selected. | | doubleMonth | boolean | false | Display two consecutive calendar months. | | dateFormat | string | 'YYYY-MM-DD' | Output format, for example 'DD/MM/YYYY'. | | lang | string/object | 'es' | 'es', 'en', or a partial/custom translation object. | | actions | array | ['close', 'today', 'now', 'clear'] | Footer buttons in the supplied order; [] hides them. Today requires the calendar; Now requires the clock; Close closes input dropdowns. |

🔄 Callbacks / Events

| Callback | Default | Parameters and behavior | | --- | --- | --- | | onOpen | No-op function | No arguments. Runs when a picker opens; this is the target element. | | onClose | No-op function | No arguments. Runs when a picker closes, including when another input picker opens; this is the target element. | | onSelectDate | null | (dateObj, formattedDates): a Date for single/birthday, an array of dates for range/multiple, and an array of formatted strings. Clear or a blocked birthday edit returns (null, []). Today also invokes this callback. | | onSelectTime | null | (timeState): { hour, minute }, plus ampm in 12-hour mode. Range mode returns an array of start/end time objects. |

$("#my-datepicker").extendedDateTimePicker({
  onSelectDate(date, formattedDates) {
    console.log("Selected dates:", formattedDates);
  },
  onSelectTime(time) {
    console.log("Selected time:", time);
  },
});

$("#my-datepicker").on("change", function () {
  console.log("Form value:", this.value);
});

Form behavior:

• Initialization does not emit selection callbacks or input/change events.
• User edits emit input and change when the input value changes.
• An existing input value is preserved when no initial date selection is supplied, except in clock-only mode, which initializes the time. Existing text is not parsed into a selection.
• Clear empties the input and controls. Editing again restores the controls from their last valid state.

🛠️ Public methods

$("#my-datepicker").extendedDateTimePicker("open");
$("#my-datepicker").extendedDateTimePicker("close");
$("#my-datepicker").extendedDateTimePicker("destroy");

Methods preserve jQuery chaining. Supported methods do nothing on uninitialized elements; unknown names throw an error.

Calling the plugin again with options replaces the current instance. destroy removes plugin controls/listeners and restores the input's original attributes. It does not restore content previously removed from an inline container.

🌍 Languages

Spanish is the default. Select English with lang: "en", or customize individual labels:

$("#my-datepicker").extendedDateTimePicker({
  lang: {
    actions: { clear: "Reset selection", close: "Close picker" },
  },
});

Partial custom dictionaries and unknown language codes fall back to Spanish. To customize English labels without Spanish fallbacks, start from the complete English dictionary:

import en from "jquery-extended-datetimepicker/langs/en.json";

en.actions.clear = "Reset selection";
$("#my-datepicker").extendedDateTimePicker({ lang: en });

JSON imports require bundler support; direct Node.js JSON imports may require import attributes. Dictionary exports are available starting with version 1.5.3.

Custom dictionary rules:

• calendar, clock, birthday, and actions must be objects when supplied.
• Labels must be strings; translations are displayed as plain text, not HTML.
• Month arrays require 12 strings; weekday arrays require 7 strings.
• Calendar weekday labels use calendar.weekdaysShort.
• Accessible labels use calendar.title, calendar.previous, calendar.next, and clock/birthday keys increase and decrease.
• Range clock headings use clock.start and clock.end.

For contributors, src/js/modules/i18n.js is the single editable source. Run npm run langs:sync to regenerate langs/es.json and langs/en.json; do not edit the generated JSON files by hand. The build also regenerates them.

⌨️ Keyboard and layout

| Key | Action | | --- | --- | | Tab / Shift+Tab | Move between controls. | | Arrow keys on calendar days | Move one day left/right or one week up/down within the rendered calendar, skipping disabled dates. | | Enter / Space | Select a focused calendar day. | | Escape | Close an input dropdown and return focus to its input. |

The horizontal layout switches to vertical when the component's available width is small. Two-month calendars can scroll horizontally in narrow containers. Clock buttons have larger targets on touch devices, and clock-only mode omits the date/clock separator.

The component uses Bootstrap CSS variables and CSS container queries. Keep the viewport meta tag in mobile pages and use browsers with container-query support.

🧑‍💻 Local development

Use npm; package-lock.json is the dependency lockfile. The current test dependencies require Node.js ^22.22.2, ^24.15.0, or >=26.0.0.

git clone https://github.com/PinedaMB/extended_datetimepicker.git
cd extended_datetimepicker
npm ci
npm run dev

Open the local URL printed in the terminal (normally http://127.0.0.1:5173/). Changes to src/, docs/index.html, and docs/playground.css update the demo automatically. Stop the server with Ctrl+C.

The local demo uses source modules and local jQuery. Bootstrap is loaded from its CDN, so the playground still needs internet access for those assets. Development does not refresh dist/; run the build when you need distribution files.

| Command | Purpose | | --- | --- | | npm run dev | Start the local playground with automatic updates. | | npm test | Run regression tests. | | npm run build | Generate translation JSON, build ESM/browser bundles and CSS, copy assets to the demo, and synchronize its reference tables. | | npm run langs:sync | Regenerate JSON dictionaries from the source translations. | | npm run langs:check | Verify that generated dictionaries match the source. | | npm run docs:sync | Update the playground's options/callbacks tables from this README. | | npm run docs:check | Verify that those tables are synchronized. | | npm audit | Check installed dependency advisories. | | npm pack --dry-run | Inspect the package contents without publishing. |

Only the options and callbacks tables synchronize automatically from the README. Other playground documentation is maintained separately. The playground applies settings to both previews; applying with an empty initial-date field removes its previous preselection and input value.

Before preparing a release, run the build, tests, documentation/translation checks, and package inspection. Record changes under Unreleased in CHANGELOG.md, then assign the release version when publishing.

🩺 Troubleshooting

| Symptom | Check | | --- | --- | | extendedDateTimePicker is not a function | Load jQuery before the classic plugin script; with a bundler, import both from the same project. | | The picker has no styling or the layout looks wrong | Include both Bootstrap CSS and the plugin CSS. | | A configured date is missing | Use valid ISO strings and check limits, weekends, blocked dates, and birthday year bounds. | | The output is in Spanish | Set lang: "en"; partial custom dictionaries fall back to Spanish. | | Source edits do not appear in the published demo | npm run dev previews source; run npm run build to refresh distributable/demo assets before deployment. | | Translation JSON checks fail after editing labels | Run npm run langs:sync and include the regenerated JSON files in the change. |

👤 Author and license

Created and maintained by Brayan Pineda Méndez / PinedaMB.

📄 Licensed under MIT. Contributions and reproducible bug reports are welcome through GitHub Issues.