README

bsTimepicker is a jQuery time picker plugin with a Bootstrap-styled trigger and dropdown UI. It supports 12-hour and 24-hour display modes, stores values in a database-friendly 24-hour format, and works with input and div elements.

The picker uses a circular clock-style selector inspired by mobile alarm/time picker interfaces while staying easy to drop into existing Bootstrap-based forms.

Features

• jQuery plugin exposed as $.fn.bsTimepicker
• Bootstrap 4/5 styled trigger button and dropdown
• 12h and 24h display modes
• Configurable minute interval: 1, 5, 10, or 15 minutes
• Database-friendly value handling via val()
• Supports input and div root elements
• Optional hidden field support with nameField
• Touch-friendly circular dial with draggable active pointer support
• Public API for show, hide, toggle, set, get, and value access
• Event hooks for initialization, visibility changes, and value changes
• Customizable okLabel and cancelLabel with HTML support (Icons + Text)
• Automatic state revert when cancelling or clicking outside
• Compact design for better UI integration

Requirements

• jQuery 3.x
• Bootstrap 4.6.x or 5.x
• Bootstrap Icons for the default trigger icon and any icon labels you configure
• Bootstrap JS must be loaded because the plugin uses the Bootstrap dropdown component

Installation

Include your vendor assets and the plugin script.

<link rel="stylesheet" href="vendor/twbs/bootstrap/dist/css/bootstrap.min.css">
<link rel="stylesheet" href="vendor/twbs/bootstrap-icons/font/bootstrap-icons.css">

<script src="vendor/components/jquery/jquery.min.js"></script>
<script src="vendor/twbs/bootstrap/dist/js/bootstrap.bundle.min.js"></script>
<script src="dist/bs-timepicker.js"></script>

Quick start

24-hour input

<input type="text" id="time24" value="07:15">

$("#time24").bsTimepicker({
    format: "24h"
});

12-hour input

<input type="text" id="time12" value="08:45 PM">

$("#time12").bsTimepicker({
    format: "12h"
});

Div with generated hidden field

<div id="appointmentTime"></div>

$("#appointmentTime").bsTimepicker({
    format: "24h",
    defaultTime: "13:20",
    nameField: "appointment_time",
    btnClass: "btn btn-outline-primary",
    btnWidth: "220px"
});

Minute interval

$("#appointmentTime").bsTimepicker({
    format: "24h",
    minuteInterval: 15
});

Supported root elements

Input

When initialized on an input, the original input becomes the internal value field and the visible trigger button is rendered after it.

This is the best choice when the value should already exist in a normal form field.

Div

When initialized on a div, the plugin renders the trigger inside that element. If nameField is provided, a hidden input is created so the value can be submitted with a form.

Value model

The plugin separates a display format from a stored value format.

• The UI may display either 12h or 24h time.
• The stored value is intended to be a 24-hour string in HH:mm format.
• Empty values are returned as null through val().

Examples:

• Visible UI: 12:30 AM → stored value: 00:30
• Visible UI: 12:30 PM → stored value: 12:30
• Visible UI: 03:45 PM → stored value: 15:45

Options

{
    "format": "24h",
    "defaultTime": null,
    "nameField": null,
    "title": "Select time",
    "closeOnSelect": false,
    "minuteInterval": 5,
    "btnClass": "btn btn-outline-secondary",
    "btnWidth": null,
    "btnEmptyText": "--:--",
    "showClearButton": true,
    "icons": {
        "trigger": "bi bi-clock"
    },
    "clearLabel": "<span class=\"small\">Clear</span>",
    "okLabel": "<span class=\"small\">OK</span>",
    "cancelLabel": "<span class=\"small\">Cancel</span>"
}

format

Type: string

Allowed values:

• "24h"
• "12h"

Controls how the time is displayed in the picker and trigger.

defaultTime

Type: string | Date | object | null

Examples:

• "13:45"
• "01:45 PM"
• new Date()
• { hour24: 13, minute: 45 }

Used when no initial value is already present on the source element.

nameField

Type: string | null

Only relevant when the plugin is initialized on a div. Creates a hidden input with the provided name.

title

Type: string | null

Optional title is displayed at the top of the dropdown panel. Set it to null or an empty string to hide the title.

closeOnSelect

Type: boolean

When true, the picker closes automatically after selecting minutes.

minuteInterval

Type: number

Allowed values:

• 1
• 5
• 10
• 15

Controls the selectable minute steps in the minute dial. The default is 5. With minuteInterval: 1, the dial keeps 5-minute labels as visual anchors while tap and drag selection still resolves to every minute.

Examples:

minuteInterval: 1   // every minute
minuteInterval: 5   // 00, 05, 10, ...
minuteInterval: 10  // 00, 10, 20, ...
minuteInterval: 15  // 00, 15, 30, 45

btnClass

Type: string

Bootstrap classes are applied to the visible trigger button.

Example:

btnClass: "btn btn-outline-primary"

btnWidth

Type: string | null

Optional width for the trigger button.

Example:

btnWidth: "220px"

btnEmptyText

Type: string

Text shown in the trigger when no value is set.

Default is --:--.

showClearButton

Type: boolean

Shows a clear button in the picker footer that resets the value to empty (null in val()).

clearLabel

Type: string

HTML or text for the clear button.

icons

Type: object

Controls the Bootstrap Icon classes used by the trigger.

Example:

{
    "icons": {
        "trigger": "bi bi-clock"
    }
}

okLabel

Type: string

HTML or text for the confirmation button.

cancelLabel

Type: string

HTML or text for the cancel button.

Public API

Initialize

$("#time24").bsTimepicker({
    format: "24h"
});

getTime()

Returns a structured object with display and normalized values.

const data = $("#time24").bsTimepicker("getTime");

Example result:

{
    "hour24": 13,
    "minute": 40,
    "hour12": 1,
    "meridiem": "PM",
    "formatted24": "13:40",
    "formatted12": "01:40 PM",
    "formatted": "13:40",
    "isEmpty": false
}

Empty result (after clear):

{
    "hour24": null,
    "minute": null,
    "hour12": null,
    "meridiem": null,
    "formatted24": null,
    "formatted12": null,
    "formatted": null,
    "isEmpty": true
}

setTime(value)

Sets the current time.

$("#time24").bsTimepicker("setTime", "06:30");
$("#time12").bsTimepicker("setTime", "09:45 PM");

val()

Returns the stored raw value as a string in HH:mm format, or null if empty.

const raw = $("#time24").bsTimepicker("val");

Examples:

• "06:30"
• "00:30"
• null

val(value)

Sets the stored value using a string.

$("#time24").bsTimepicker("val", "12:30");
$("#time12").bsTimepicker("val", "12:30 PM");
$("#time24").bsTimepicker("val", "");

Passing "" or null clears the value and restores the empty trigger label.

clear()

Clears the value, updates the trigger label to the configured empty text, and fires change events.

$("#time24").bsTimepicker("clear");

show()

Opens the dropdown picker.

$("#time24").bsTimepicker("show");

hide()

Closes the dropdown picker.

$("#time24").bsTimepicker("hide");

toggle()

Toggles the dropdown picker.

$("#time24").bsTimepicker("toggle");

destroy()

Destroys the plugin instance and removes the generated UI.

$("#time24").bsTimepicker("destroy");

Events

The plugin can emit the following events on the original root element.

Initialization and visibility

• init.bs.timepicker
• show.bs.timepicker
• shown.bs.timepicker
• hide.bs.timepicker
• hidden.bs.timepicker

Value changes

• change.bs.timepicker
• changeHour.bs.timepicker
• changeMinutes.bs.timepicker
• timeChange.bsTimepicker
• clear.bs.timepicker

Example

$("#time24").on("shown.bs.timepicker", function (e, data) {
    console.log("Picker opened", data);
});

$("#time24").on("change.bs.timepicker", function (e, data) {
    console.log("Time changed", data);
});

$("#time24").on("changeHour.bs.timepicker", function (e, data) {
    console.log("Hour changed", data.hour24);
});

$("#time24").on("changeMinutes.bs.timepicker", function (e, data) {
    console.log("Minutes changed", data.minute);
});

Database usage

For most applications, store the value returned by val().

const dbValue = $("#time24").bsTimepicker("val");

Typical values:

• "06:30"
• "14:45"
• "00:05"
• null

In most systems there is no need to store AM or PM separately. That is usually presentation logic only.

Example form integration

Input-based field

<form>
    <input type="text" id="startTime" name="start_time" value="08:30">
</form>

$("#startTime").bsTimepicker({
    format: "24h"
});

Div-based field with hidden input

<form>
    <div id="alarmTime"></div>
</form>

$("#alarmTime").bsTimepicker({
    format: "12h",
    nameField: "alarm_time",
    btnEmptyText: "Please select a time"
});

Notes

• val() is intended for the database-friendly raw value.
• getTime() is intended for richer UI information.
• The plugin currently works with hours and minutes, not seconds.
• If your backend uses a database TIME column with seconds, you can still store the returned value and append :00 server-side if needed.

Example demo setup

<link rel="stylesheet" href="../vendor/twbs/bootstrap/dist/css/bootstrap.min.css">
<link rel="stylesheet" href="../vendor/twbs/bootstrap-icons/font/bootstrap-icons.css">

<script src="../vendor/components/jquery/jquery.min.js"></script>
<script src="../vendor/twbs/bootstrap/dist/js/bootstrap.bundle.min.js"></script>
<script src="../dist/bs-timepicker.js"></script>

License

MIT License