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 enhancedto enable the datepicker on a native input enhancedrenders a text input to avoid conflicts with native browser date pickers; without it,DatePickerretains 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.
<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
| Name | Type | Default | Description |
|---|---|---|---|
min / options.dateMin | string, number, Date | null | Minimum selectable date. Format: YYYY-MM-DD |
max / options.dateMax | string, number, Date | null | Maximum selectable date. Format: YYYY-MM-DD |
options.dateFormat | object, function | null | Date formatting. Pass Intl.DateTimeFormat options or a function(date, locale). |
options.displayElement | string, element, boolean | null | Element to show formatted date. For buttons, defaults to the button itself. Set to false to disable. |
displayMonthsCount | number | 1 | Number of months to display side-by-side in the calendar. |
firstWeekday | number | 1 | First day of week (0 = Sunday, 1 = Monday, etc.) |
inline | boolean | false | Render calendar inline (always visible, no popup). |
options.locale | string | 'default' | Locale for date formatting (e.g., 'en-US', 'de-DE') |
options.positionElement | string, element | null | Element to position the calendar relative to. Automatically detects FormAdornment when present. |
selectedDates | array | [] | Pre-selected dates in YYYY-MM-DD format |
selectionMode | string | 'single' | Selection mode: 'single', 'multiple', or 'multiple-ranged' |
placement | string | 'left' | Calendar position relative to input: 'left', 'center', 'right', 'auto' |
datepickerTheme | string | null | Force datepicker popup theme: 'light', 'dark', 'auto', or null to inherit from ancestor [data-bs-theme] |
options.vcpOptions | object | {} | Pass-through object for any Vanilla Calendar Pro option |