README

Bootstrap Pickadate is a small date picker for Bootstrap 5.3 and modern browsers.

It is intentionally focused on date selection. It does not provide time picking, recurrence, event scheduling, remote loading, or calendar-application features.

Requirements

• Bootstrap 5.3.x
• Bootstrap Icons ^1 for the default navigation icons

Files

Typical package files:

bootstrap-pickadate.css
bootstrap-pickadate.less
bootstrap-pickadate.js
locales/bootstrap-pickadate.<locale>.js

Load the CSS first, then Bootstrap, then Bootstrap Pickadate, then any locale files you need.

<link rel="stylesheet" href="bootstrap-pickadate.css">
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js"></script>
<script src="bootstrap-pickadate.js"></script>
<script src="locales/bootstrap-pickadate.it.js"></script>

Basic usage

<label for="event_date_display" class="form-label">Date</label>
<div class="input-group">
    <input
        id="event_date_display"
        type="text"
        class="form-control bootstrap-pickadate"
        data-bs-pickadate-locale="current"
        data-bs-pickadate-hidden-target="#event_date"
    >
    <button class="btn btn-outline-secondary" type="button" data-bs-pickadate-toggle="#event_date_display">
        <i class="bi bi-calendar-date"></i>
    </button>
    <button class="btn btn-outline-secondary" type="button" data-bs-pickadate-clear="#event_date_display">
        <i class="bi bi-x-lg"></i>
    </button>
</div>
<input id="event_date" name="event_date" type="hidden">

The visible field uses the active locale format. The hidden field receives an ISO date:

yyyy-mm-dd

Two-input range usage

Use two separate visible inputs when the form needs independent start and end fields.

<input
    id="date_from_display"
    class="form-control bootstrap-pickadate"
    data-bs-pickadate-hidden-target="#date_from"
    data-bs-pickadate-range-role="start"
    data-bs-pickadate-range-pair="#date_to_display"
>
<input id="date_from" name="date_from" type="hidden">

<input
    id="date_to_display"
    class="form-control bootstrap-pickadate"
    data-bs-pickadate-hidden-target="#date_to"
    data-bs-pickadate-range-role="end"
    data-bs-pickadate-range-pair="#date_from_display"
>
<input id="date_to" name="date_to" type="hidden">

When the start date changes, the end picker receives that date as its runtime minimum. When the end date changes, the start picker receives that date as its runtime maximum.

Same-input interval usage

Use interval mode when one field should select a complete date interval, like booking/travel forms.

<input
    id="booking_dates_display"
    class="form-control bootstrap-pickadate"
    data-bs-pickadate-mode="interval"
    data-bs-pickadate-hidden-target="#booking_dates"
    data-bs-pickadate-hidden-start-target="#booking_start"
    data-bs-pickadate-hidden-end-target="#booking_end"
>
<input id="booking_dates" name="booking_dates" type="hidden">
<input id="booking_start" name="booking_start" type="hidden">
<input id="booking_end" name="booking_end" type="hidden">

The combined hidden interval value is stored as:

yyyy-mm-dd/yyyy-mm-dd

Interval behaviour:

First click: choose start date.
Hover: preview the possible interval.
Second click: choose end date.
Further click after a complete interval: reset and start a new interval immediately.

In interval mode the picker shows two side-by-side months. Duplicated overlap days between the first and second month are hidden to avoid visual confusion.

Data attributes

JavaScript API

const picker = new bsPickadate("event_date_display", {
    locale: "it",
    hiddenTarget: "#event_date",
    min: "2026-01-01",
    max: "2026-12-31"
});

picker.value("2026-06-24");
picker.value();
picker.clear();
picker.today();
picker.open();
picker.close();
picker.setMin("2026-01-01");
picker.setMax("2026-12-31");
picker.destroy();

Locale handling

Locale files register themselves in:

window.bootstrapPickadateLocales

The fallback chain is:

selected full locale -> selected base language -> configured default -> en

For example:

pt_BR -> pt -> it -> en

A website can set the active language after a navbar language change:

bsPickadate.setDefaultLocale("it");
bsPickadate.refreshAll();

Month selector format

Locales can define a compact month label format for the month selector:

monthShortFormat: "mm mmm"

Supported tokens:

Examples:

// English
monthShortFormat: "mmm mm" // Feb 02

// Italian
monthShortFormat: "mm mmm" // 02 feb

The full month name is still available to the component for labels and accessibility.

Global registry

Bootstrap Pickadate keeps active instances in:

window.FORM.pickadate

This keeps the component consistent with the Bootstrap Select architecture used in related packages.

Optional jQuery integration

Bootstrap Pickadate is a plain JavaScript component and does not require jQuery.

If you want a jQuery-style application layer, gianlucagiacometti/web-toolbox provides jquery-bootstrap-pickadate. The wrapper keeps Bootstrap Pickadate as the underlying component and adds jQuery initialisation plus method-style calls.

composer require gianlucagiacometti/web-toolbox

Suggested script order:

<link rel="stylesheet" href="/assets/bootstrap-pickadate/bootstrap-pickadate.css">
<script src="/assets/jquery/jquery.min.js"></script>
<script src="/assets/bootstrap/js/bootstrap.bundle.min.js"></script>
<script src="/assets/bootstrap-pickadate/bootstrap-pickadate.js"></script>
<script src="/assets/bootstrap-pickadate/locales/bootstrap-pickadate.it.js"></script>
<script src="/assets/jquery-bootstrap-pickadate/jquery-bootstrap-pickadate.js"></script>

$("input.bootstrap-pickadate").jqueryBootstrapPickadate({
    locale: "current"
});

Versioning

The intended version line follows Bootstrap compatibility:

5.3.x targets Bootstrap 5.3.x

Version 5.3.0 introduces the cached-DOM refactor and same-input interval mode.