API reference · Date Range Picker 4

Options

Pass an options object as the second constructor argument. HTML data attributes such as data-single-calendar="true" also work. Constructor options override attributes on the trigger.

const picker = new DateRangePicker('#dates', {
  locale: { format: 'YYYY-MM-DD' },
  startDate: '2026-06-01',
  endDate: '2026-06-07',
  maxSpan: { days: 30 }
});

Date inputs include a JavaScript Date, a millisecond timestamp, a local date array with a zero-based month, and a string matching locale.format. You can also pass a picker date or a Moment object.

Dates and bounds

startDatedate input · Today, start of day: Initial start of the selection. A populated text input can supply the starting range when both initial date options are omitted.
endDatedate input · Today, end of day: Initial end of the selection. Without time selection, dates cover the whole local day.
minDatedate input or false · false: Earliest selectable date. Include a time to set a lower bound on time selection.
maxDatedate input or false · false: Latest selectable date. Include a time to set an upper bound on time selection.
minSpanspan object · Unset: Minimum elapsed span for a range. With { days: 2 }, a Monday start can end on Wednesday or later.
maxSpanspan object · Unset: Maximum elapsed span from the start. Supply a duration object such as { days: 30 } or { hours: 8 }. The legacy alias is dateLimit.
rangeslabel → date pair · Unset: Display named presets. Each value is an array of two date inputs. Use setRanges() to replace the list after mounting.

Calendars and selection

singleDatePickerboolean · false: Choose a single date in one calendar. Both ends of the selection represent that date.
singleCalendarboolean · false: Choose both ends of a range in one calendar. When time selection is enabled, both time selectors remain available.
linkedCalendarsboolean · true: Show consecutive months and navigate them together. Set to false for independent month navigation.
alwaysShowCalendarsboolean · false: Keep the calendar visible alongside the preset list.
showCustomRangeLabelboolean · true: Include the custom range entry after the presets.
applyOnRangeClickboolean · true: Apply a preset as soon as it is chosen. Set to false to allow editing before Apply. Auto-apply in date-only mode still commits a preset immediately.
showDropdownsboolean · false: Show month and year selectors in the calendar headers.
minYearnumber · Current year − 100: Earliest year in the year dropdown when no minimum date is set.
maxYearnumber · Current year + 100: Latest year in the year dropdown when no maximum date is set.
showWeekNumbersboolean · false: Show locale week numbers in the first column.
showISOWeekNumbersboolean · false: Show ISO week numbers. When both week settings are enabled, locale week numbers take precedence.
autoApplyboolean · false: Commit a completed date selection automatically and hide the action buttons. Time selection always uses the action buttons.
autoUpdateInputboolean · true: Write the formatted selection into the attached input on initialization and update. Set to false to keep an input initially empty or control its text yourself.

Time selection

timePickerboolean · false: Show time selectors alongside the calendars. Include time tokens in locale.format to display the time in the input.
timePicker24Hourboolean · false: Use 24-hour time instead of AM and PM controls.
timePickerSecondsboolean · false: Add a seconds selector.
timePickerIncrementinteger, 1–60 · 1: Spacing between minute choices. For example, 15 offers minutes 00, 15, 30 and 45.

Appearance and placement

localeobject · Active date locale: Customize labels, formatting, week order and text direction. See the locale fields.
parentElselector or element · body: Append the dropdown inside this container. A positioned wrapper can anchor a picker inside a dialog.
opensright | left | center · right: Align the dropdown horizontally relative to the trigger. The legacy pull-right class selects left alignment by default.
dropsdown | up | auto · down: Open above or below the trigger. Auto uses the available vertical space. A trigger with dropup defaults to up.
buttonClassesstring or string[] · btn btn-sm: CSS classes shared by the Apply and Cancel buttons.
applyButtonClassesstring · btn-primary: Additional Apply button classes. The legacy alias is applyClass.
cancelButtonClassesstring · btn-default: Additional Cancel button classes. The legacy alias is cancelClass.
templateHTML string or element · Built-in template: Supply custom markup with the same calendar containers, ranges list and button class hooks as the built-in template.

Date hooks

isInvalidDatefunction(date) · Returns false: Return true to disable an endpoint. For example, date => date.day() === 0 disables Sundays.
isCustomDatefunction(date) · Returns false: Return a CSS class, an array of classes, or false for each day cell. Use your stylesheet to style the returned classes.

Locale fields

Pass any of these keys inside locale. The standalone defaults use English. With Moment present, the picker reads its default format, weekday and month names, and first day of the week from the active Moment locale.

formatstring · MM/DD/YYYY in English: Date and time format for text inputs and string options. For example, YYYY-MM-DD HH:mm shows a 24-hour time.
separatorstring · " - ": Text between the two formatted endpoints in a range input.
firstDaynumber · 0 in English: First weekday shown. Sunday is 0 and Monday is 1.
daysOfWeek, monthNamesstring arrays: Seven weekday labels starting with Sunday and twelve month labels starting with January. The picker rotates weekday headings to match firstDay.
applyLabel, cancelLabelstrings · Apply, Cancel: Text on the action buttons.
weekLabel, customRangeLabelstrings · W, Custom Range: Heading for week numbers and the entry for a custom date range.
directionltr | rtl · ltr: Calendar layout direction. Right-to-left also reverses left and right arrow-key navigation.

Methods and state

The constructor returns the picker. Read picker.startDate and picker.endDate for the current selection. Between the two clicks of a range selection, endDate is null. Read chosenLabel for the preset label and isShowing for visibility.

setStartDate(value) setEndDate(value): Update an endpoint with a supported date input. Bounds and span limits still apply.
setRanges(ranges): Replace the preset list with a new object. Pass null to remove the list.
show(), hide(), toggle(): Control visibility. Hiding an incomplete selection restores the previous dates.
showCalendars(), hideCalendars(): Reveal or hide the calendar portion of a preset picker.
move(): Recalculate the dropdown position after a layout change.
remove(): Remove the dropdown and the instance’s event listeners during component teardown.
DateRangePicker.getInstance(element): Look up an instance from its DOM trigger. Returns undefined after removal.
DateRangePicker.installJQuery($, moment?): Register the plugin on a module-private jQuery instance. Supply Moment to use its date objects and locale.

Use format() to display a picker date and toDate() for a native date. Date setters, add(), subtract(), startOf() and endOf() mutate the picker date. Call clone() before changing a date you read from the instance.

Events and callbacks

Native events bubble from the trigger. Register the full name, including .daterangepicker, and read the instance from event.detail. jQuery handlers receive the picker as their second argument.

const input = document.querySelector('#dates');
input.addEventListener('apply.daterangepicker', event => {
  const { startDate, endDate } = event.detail;
  console.log(startDate.toDate(), endDate.toDate());
});

show.daterangepicker hide.daterangepicker: The dropdown has opened or closed.
apply.daterangepicker: The user applied a range, including a preset that applies immediately. Fires even when the dates match the previous selection.
cancel.daterangepicker: The user canceled the edit and the picker restored its previous dates.
selectStart.daterangepicker selectEnd.daterangepicker: A calendar interaction selected a start or end date. Listen here for in-progress edits before Apply.
showCalendar.daterangepicker hideCalendar.daterangepicker: The picker revealed or hid its calendar panels.
calendarRendered.daterangepicker: The picker has redrawn its month grids, including during month navigation.
outsideClick.daterangepicker: An interaction outside the dropdown dismissed it.
change: A bubbling native input event fires when the picker writes a different formatted value with autoUpdateInput enabled.

The optional third constructor argument is a callback. It receives copies of the start and end dates and the chosen label when the picker closes with a changed selection.

new DateRangePicker('#dates', {}, (start, end, label) => {
  console.log(label, start.format('YYYY-MM-DD'), end.format('YYYY-MM-DD'));
});