Loading...
Skip to main content

Datepicker

A flexible calendar and date picker popover with support for input or button toggles, range selection, multiple months, and more.

Overview

The Bootstrap Datepicker is a wrapper around Vanilla Calendar Pro that provides a consistent, accessible date selection experience. It supports light/dark themes, input binding, and flexible configuration via React props.

<>
<FormLabel htmlFor="datepicker1">
Datepicker
</FormLabel>
<DatePicker
autoComplete="off"
className="w-12"
enhanced
id="datepicker1"
placeholder="Choose date…"
/>
</>

The example applies a width utility through className so the input can accommodate the date format and suggest the expected type of input.

How it works

  • Use DatePicker enhanced to enable the datepicker on a native input
  • enhanced renders a text input to avoid conflicts with native browser date pickers; without it, DatePicker retains the browser’s native date input
  • When focused, the calendar popup appears below the input
  • Selecting a date updates the input value and closes the picker
  • The picker also closes on a click outside it, on Escape, or when focus moves to an element outside it
  • The picker respects Bootstrap’s color modes (data-bs-theme)
  • Configurable with any Vanilla Calendar Pro option via options.vcpOptions

Examples

With form field

Use the form field component to layout and wrap your inputs with a label, description, and validation feedback messages in a vertical stack.

We’ll never share your email with anyone else.
<FormField>
<FormLabel htmlFor="datepicker2">
Datepicker field
</FormLabel>
<DatePicker
autoComplete="off"
className="w-12"
enhanced
id="datepicker2"
placeholder="Choose date…"
/>
<FormText>
{' '}We’ll never share your email with anyone else.{' '}
</FormText>
</FormField>

With icon

Use the form adorn component to add a calendar icon alongside the datepicker input. When the input is inside FormAdornment, the calendar automatically positions relative to the wrapper instead of the input.

<>
<FormLabel htmlFor="datepickerIconStart">
Select date
</FormLabel>
<FormAdornment className="w-12">
<FormAdornmentIcon
aria-hidden="true"
name="calendar-week"
/>
<DatePicker
autoComplete="off"
enhanced
ghost
id="datepickerIconStart"
placeholder="Choose date…"
/>
</FormAdornment>
</>

Min & Max dates

Restrict the selectable date range using the min and max props.

<>
<FormLabel htmlFor="datepickerMinMax">
Event date (2026 only)
</FormLabel>
<DatePicker
autoComplete="off"
className="w-12"
enhanced
id="datepickerMinMax"
max="2026-12-31"
min="2026-01-01"
placeholder="Select a date in 2026"
/>
</>

Multiple dates

Enable multiple date selection with selectionMode="multiple".

<>
<FormLabel htmlFor="datepicker3">
Select multiple dates
</FormLabel>
<DatePicker
autoComplete="off"
enhanced
id="datepicker3"
placeholder="Select date range…"
selectionMode="multiple"
/>
</>

Multiple months

Display multiple months side-by-side with the displayMonthsCount option. This is useful for date range selection where users need to see more context.

<>
<FormLabel htmlFor="datepickerMultiMonth">
Select date range
</FormLabel>
<DatePicker
autoComplete="off"
displayMonthsCount={2}
enhanced
id="datepickerMultiMonth"
placeholder="Select start and end dates"
selectionMode="multiple-ranged"
/>
</>

Date range

Select a range of dates with selectionMode="multiple-ranged". Use selectedDates to preselect a date range.

<>
<FormLabel htmlFor="datepicker4">
Select date range
</FormLabel>
<DatePicker
autoComplete="off"
enhanced
id="datepicker4"
placeholder="Select start and end dates…"
selectedDates={[
'2026-06-10',
'2026-06-18'
]}
selectionMode="multiple-ranged"
/>
</>

Multi-month date range

For selecting date ranges that span multiple months, combine selectionMode="multiple-ranged" with displayMonthsCount={2} to show two months side-by-side, making it easier for users to select across month boundaries.

<>
<FormLabel htmlFor="datepickerRangeTwoMonths">
Select date range
</FormLabel>
<DatePicker
autoComplete="off"
displayMonthsCount={2}
enhanced
id="datepickerRangeTwoMonths"
placeholder="Select start and end dates…"
selectedDates={[
'2026-06-25',
'2026-07-08'
]}
selectionMode="multiple-ranged"
/>
</>

Options

First day of week

Set the first day of the week (0 = Sunday, 1 = Monday, etc.) with firstWeekday.

<>
<FormLabel htmlFor="datepicker6">
Week starts on Sunday
</FormLabel>
<DatePicker
autoComplete="off"
className="w-12"
enhanced
firstWeekday={0}
id="datepicker6"
placeholder="Select a date"
/>
</>

Placement

Control where the calendar appears relative to the input with placement. Options are left (default), center, right, and auto.

<div className="d-flex gap-3">
<div>
<FormLabel htmlFor="datepickerLeft">
Left aligned
</FormLabel>
<DatePicker
autoComplete="off"
enhanced
id="datepickerLeft"
placeholder="Left"
placement="left"
/>
</div>
<div>
<FormLabel htmlFor="datepickerCenter">
Center aligned
</FormLabel>
<DatePicker
autoComplete="off"
enhanced
id="datepickerCenter"
placeholder="Center"
placement="center"
/>
</div>
<div>
<FormLabel htmlFor="datepickerRight">
Right aligned
</FormLabel>
<DatePicker
autoComplete="off"
enhanced
id="datepickerRight"
placeholder="Right"
placement="right"
/>
</div>
</div>

Button trigger

Use DatePickerButton instead of an input for use cases like dashboard date filters. Set leadingIcon to preserve an icon when the date updates.

<DatePickerButton
leadingIcon="calendar-week"
theme="secondary"
type="button"
variant="outline"
>
Select date
</DatePickerButton>

For date range selection (e.g., dashboard time filters), use selectionMode="multiple-ranged". The calendar will close after both start and end dates are selected.

<DatePickerButton
leadingIcon="calendar-week"
selectionMode="multiple-ranged"
theme="secondary"
type="button"
variant="outline"
>
Last 7 days
</DatePickerButton>

You can also display the selected date in a separate element using options.displayElement:

<DatePickerButton
selectionMode="multiple-ranged"
options={{ displayElement: "#date-display" }}
>
Choose dates
</DatePickerButton>
<span id="date-display" />

Inline mode

Render the calendar inline (always visible, no popup) with DatePickerInline. This is useful for embedding a calendar directly in the page.

<DatePickerInline />

Inline datepickers with date range selection:

<DatePickerInline selectionMode="multiple-ranged" />

Multiple months inline:

<DatePickerInline displayMonthsCount={2} />

To bind to a form field, include a hidden input inside the container. The value will be updated with the selected date(s) in YYYY-MM-DD format:

<Form>
<DatePickerInline>
<FormControl
name="selected_date"
type="hidden"
/>
</DatePickerInline>
<Button
className="mt-3"
theme="primary"
type="submit"
variant="solid"
>
Submit
</Button>
</Form>

Custom date formatting

Control how dates are displayed using options.dateFormat. Pass an Intl.DateTimeFormat options object or a custom function.

<DatePicker
enhanced
options={{ dateFormat: { month: "short", day: "numeric", year: "numeric" } }}
/>
<DatePicker
enhanced
options={{ dateFormat: (date, locale) => date.toLocaleDateString(locale, { month: "short", day: "numeric" }) }}
/>

Dark mode

The datepicker automatically adapts to Bootstrap’s color modes. When data-bs-theme="dark" is set on a parent element or the <html> tag, the calendar popup inherits that theme.

Inherited from parent

When a parent element has a theme, both the input and calendar popup inherit it:

<div
className="p-3 bg-body fg-body rounded"
data-bs-theme="dark"
>
<FormLabel htmlFor="datepickerDark">
Dark mode datepicker
</FormLabel>
<DatePicker
autoComplete="off"
enhanced
id="datepickerDark"
placeholder="Select a date"
/>
</div>

Datepicker-only theme

Use datepickerTheme to set the datepicker popup’s theme independently of the input. This is useful when you want a light input with a dark datepicker, or vice versa:

<>
<FormLabel htmlFor="datepickerTheme">
Light input, dark datepicker
</FormLabel>
<DatePicker
autoComplete="off"
className="w-12"
datepickerTheme="dark"
enhanced
id="datepickerTheme"
placeholder="Select a date"
/>
</>

CSS

Variables

.example {
--bs-datepicker-padding: 1rem;
--bs-datepicker-bg: var(--bs-bg-body);
--bs-datepicker-color: var(--bs-fg-body);
--bs-datepicker-border-color: var(--bs-border-color-translucent);
--bs-datepicker-border-width: var(--bs-border-width);
--bs-datepicker-border-radius: var(--bs-radius-7);
--bs-datepicker-box-shadow: var(--bs-box-shadow);
--bs-datepicker-font-size: var(--bs-font-size-sm);
--bs-datepicker-min-width: 280px;
--bs-datepicker-zindex: var(--bs-z-menu);
--bs-datepicker-header-font-weight: 600;
--bs-datepicker-weekday-color: var(--bs-fg-3);
--bs-datepicker-day-hover-bg: var(--bs-bg-1);
--bs-datepicker-day-selected-bg: var(--bs-primary-bg);
--bs-datepicker-day-selected-color: var(--bs-primary-contrast);
--bs-datepicker-day-today-bg: var(--bs-bg-2);
--bs-datepicker-day-today-color: var(--bs-fg-1);
--bs-datepicker-day-disabled-color: var(--bs-fg-4);
}

Usage

DatePicker enhanced, DatePickerButton, and DatePickerInline initialize and dispose the calendar automatically. Pass supported settings as props, plugin settings through options and advanced Vanilla Calendar Pro settings through options.vcpOptions, and receive selected dates with onDatesChange.

Options

NameTypeDefaultDescription
min / options.dateMinstring, number, DatenullMinimum selectable date. Format: YYYY-MM-DD
max / options.dateMaxstring, number, DatenullMaximum selectable date. Format: YYYY-MM-DD
options.dateFormatobject, functionnullDate formatting. Pass Intl.DateTimeFormat options or a function(date, locale).
options.displayElementstring, element, booleannullElement to show formatted date. For buttons, defaults to the button itself. Set to false to disable.
displayMonthsCountnumber1Number of months to display side-by-side in the calendar.
firstWeekdaynumber1First day of week (0 = Sunday, 1 = Monday, etc.)
inlinebooleanfalseRender calendar inline (always visible, no popup).
options.localestring'default'Locale for date formatting (e.g., 'en-US', 'de-DE')
options.positionElementstring, elementnullElement to position the calendar relative to. Automatically detects FormAdornment when present.
selectedDatesarray[]Pre-selected dates in YYYY-MM-DD format
selectionModestring'single'Selection mode: 'single', 'multiple', or 'multiple-ranged'
placementstring'left'Calendar position relative to input: 'left', 'center', 'right', 'auto'
datepickerThemestringnullForce datepicker popup theme: 'light', 'dark', 'auto', or null to inherit from ancestor [data-bs-theme]
options.vcpOptionsobject{}Pass-through object for any Vanilla Calendar Pro option
Documentation navigation
On this page
On this page