Web Date Range Picker

DatePicker Public Interface

All attributes, methods, events, and callbacks available on the <web-daterangepicker> element.

Public API

Attributes, methods, events, and callbacks

Attributes

Attribute	Type	Default
`auto-close`	never \| selection \| apply	selection
`calendar-open-trigger`	focus \| typing \| manual	focus
`calendar-placement`	string (Floating UI)	bottom-start
`date-format-mask`	string	YYYY-MM-DD
`disabled`	boolean	false
`disabled-dates`	string (comma-sep ISO dates)	-
`disabled-dates-handling`	allow \| prevent \| block \| split \| individual	allow
`disabled-weekdays`	string (comma-sep)	-
`enable-transitions`	boolean	false
`display-format-mask`	string	-
`grid-columns`	number	-
`grid-rows`	number	-
`highlight-disabled-in-range`	boolean	true
`initial-date`	string (YYYY-MM-DD)	today
`input-size`	xs \| sm \| md \| lg \| xl	md
`locale`	string \| auto	auto
`max-date`	string (YYYY-MM-DD)	-
`min-date`	string (YYYY-MM-DD)	-
`month-layout`	horizontal \| grid	horizontal
`placeholder`	string	-
`mobile-modal-breakpoint`	CSS length	-
`mobile-modal-min-height`	CSS length	-
`positioning-mode`	floating \| inline \| modal	floating
`rolling-month-range`	string (MM-MM)	01-12
`rolling-year-range`	string (YYYY or YYYY-YYYY)	±1 year
`selection-mode`	single \| range \| multiple	single
`show-apply-button`	boolean	auto
`show-clear-button`	boolean	true
`show-debug-info`	boolean	false
`show-summary`	boolean	true
`show-today-button`	boolean	true
`unified-header-interactive`	boolean	false
`unified-navigation`	boolean	false
`unified-navigation-anchor-index`	number	0
`value`	string	-
`visible-months-count`	number	1
`week-start-day`	auto \| 0-6	auto
Member-mapping attributes (override `specialDates` property names)
`date-member`	string	date
`badge-text-member`	string	badgeText
`badge-class-member`	string	badgeClass
`badge-tooltip-member`	string	badgeTooltip
`day-class-member`	string	dayClass
`day-tooltip-member`	string	dayTooltip
`is-disabled-member`	string	isDisabled

Methods

Method	Returns	Description
`clearSelection()`	void	Clear current selection
`getInputValue()`	string	Get input value as string
`hide()`	void	Hide the calendar popup
`hideMessage()`	void	Hide the message overlay
`setInputValue(value)`	void	Set input value
`setMonthNames(names)` deprecated	void	Use the `monthNames` property setter instead
`setRollingItemAlignment(alignment)`	void	Set rolling selector alignment
`show()`	void	Show the calendar popup
`showMessage(html, type?, autoHide?)`	void	Display message overlay. `type`: `error \| warning \| info \| success`; `autoHide`: milliseconds
`toggle()`	void	Toggle calendar visibility
Selection state is exposed as properties, not methods: read/write `selectedDate`, `selectedDates`, `selectedRanges`, `isOpen`, `value`.

Events & Callbacks

Event/Callback	Type	Description
DOM Events
`date-select`	CustomEvent	Fired when a date is selected (single mode) or a range is committed (range/multiple mode, after Apply if shown). Detail shape varies by selection mode and `disabled-dates-handling`.
`change`	CustomEvent	Alias of `date-select` — fires alongside it with identical detail.
`custom-action`	CustomEvent	Fired by any button with `data-action="custom"` (action buttons or buttons inside `showMessage()` HTML). Detail contains the button's `data-*` attributes as camelCase keys.
Note: there are no `calendar-show`, `calendar-hide`, `date-change`, apply, or cancel events. Use `isOpen` for visibility state, listen for `date-select` for commits, and use `beforeDateSelectCallback` to gate selection.
Callback Properties
`badgeTooltipCallback`	Function	Custom badge tooltip HTML
`beforeDateSelectCallback`	Function	Validate/adjust before selection
`beforeMonthChangedCallback`	Function	Bulk load metadata before render
`customStylesCallback`	Function	Inject CSS into Shadow DOM
`dayTooltipCallback`	Function	Custom day tooltip HTML
`formatSummaryCallback`	Function	Custom summary formatting
`getDateMetadataCallback`	Function	Return DateInfo for custom styling
`getMonthHeaderCallback`	Function	Custom individual month header text
`getUnifiedHeaderCallback`	Function	Custom unified header text
`renderDayCallback`	Function	Full custom day cell rendering
`renderDayContentCallback`	Function	Augment default day rendering

Properties (Complex Data & State)

JavaScript-only setters for arrays, objects, and reactive selection state

Complex Data (property-wins)

Property	Type
`specialDates`	DecoratedDate[]
`disabledDates`	(Date \| string)[]
`actionButtons`	ActionButton[]
`customStrings`	Partial<LocaleStrings>
`monthNames`	string[] (length 12)
Member-mapping (also available as HTML attributes)
`dateMember`	string
`badgeTextMember`	string
`badgeClassMember`	string
`badgeTooltipMember`	string
`dayClassMember`	string
`dayTooltipMember`	string
`isDisabledMember`	string

Reactive Selection State

Property	Type	Notes
`selectedDate`	Date \| null	Single mode; get/set
`selectedDates`	Date[]	Multiple mode; get/set
`selectedRanges`	DateRange[]	Range mode; get/set
`isOpen`	boolean	Calendar visibility; get/set
`value`	string	Formatted input value; get/set

Precedence Rule

Complex-data properties accept values that can't fit in an HTML attribute (objects, callbacks, Date instances).

Precedence:

If a property is set in JavaScript, the attribute is ignored.
If only the HTML attribute is set (e.g. disabled-dates="2026-12-25"), it is parsed and used.
Property setters survive across attribute changes — the element re-applies them on every re-init.

As of v1.11.0 most setters route through updateOptions() and preserve selection / scroll / focus state. Structural changes (positioningMode, selectionMode, visibleMonthsCount, layout) still trigger a full rebuild.

CSS Custom Properties

Complete CSS custom properties for theming control. Variables are organized into base variables (foundation) and semantic component-specific variables.

Global scale: set --drp-rem (default 10px) on the host element to rescale the entire calendar. Every spacing and font token is calc(N * var(--drp-rem)).

<web-daterangepicker style="--drp-rem: 12px"></web-daterangepicker>

Base Variables

Foundation colors, typography, spacing, and layout properties

Colors & Typography

Variable	Default
Colors
`--drp-accent-color`	#3b82f6
`--drp-accent-color-hover`	#2563eb
`--drp-text-color-on-accent`	#ffffff
`--drp-border-color`	#e5e7eb
`--drp-dropdown-bg`	#ffffff
`--drp-primary-bg`	#f3f4f6
`--drp-primary-bg-hover`	#e5e7eb
`--drp-text-primary`	#111827
`--drp-text-secondary`	#6b7280
Typography
`--drp-font-size-2xs`	10px
`--drp-font-size-xs`	0.75rem
`--drp-font-size-sm`	0.875rem
`--drp-font-size-base`	1rem
`--drp-font-size-lg`	1.125rem
`--drp-font-size-xl`	20px
`--drp-font-size-2xl`	24px
`--drp-font-weight-normal`	400
`--drp-font-weight-medium`	500
`--drp-font-weight-semibold`	600
`--drp-line-height-tight`	1.25
`--drp-line-height-normal`	1.5
`--drp-line-height-relaxed`	1.75

Spacing & Other

Variable	Default
Spacing
`--drp-spacing-lg`	1.5rem
`--drp-spacing-md`	1rem
`--drp-spacing-sm`	0.5rem
`--drp-spacing-xl`	2rem
`--drp-spacing-xs`	0.25rem
Layout / Border Radius
`--drp-border-radius-sm`	4px (day cells, tooltips)
`--drp-border-radius-md`	6px (input, buttons)
`--drp-border-radius-lg`	8px (calendar, selectors)
`--drp-border-radius`	alias for -md
`--drp-border-width-base`	1px
`--drp-border`	1px solid --drp-border-color
`--drp-shadow-xl`	0 20px 25px...
Transitions
`--drp-easing-snappy`	cubic-bezier(...)
`--drp-transition-base`	200ms
`--drp-transition-fast`	150ms

Description

Input Variables

Complete input element styling control

Input Colors

Variable	Default
`--drp-input-bg`	--drp-dropdown-bg
`--drp-input-color`	--drp-text-primary
`--drp-input-border`	--base-input-border
`--drp-input-border-hover`	--base-input-border-hover
`--drp-input-border-focus`	--base-input-border-focus
`--drp-input-placeholder-color`	--drp-text-secondary
`--drp-input-bg-disabled`	--drp-primary-bg

Input Sizes

Variable	Default
`--drp-input-size-xs-height`	--base-input-size-xs-height (31px)
`--drp-input-size-sm-height`	--base-input-size-sm-height (33px)
`--drp-input-size-md-height`	--base-input-size-md-height (35px)
`--drp-input-size-lg-height`	--base-input-size-lg-height (38px)
`--drp-input-size-xl-height`	--base-input-size-xl-height (41px)

Input States

Variable	Default
`--drp-input-focus-shadow-color`	rgba(59, 130, 246, 0.1)
`--drp-input-focus-shadow-size`	3px
`--drp-input-icon-opacity`	0.5

Day Cell Variables

Day cell colors, states, and interactions

Basic States

Variable	Default
`--drp-day-bg-hover`	--drp-primary-bg
`--drp-day-border`	2px solid transparent
`--drp-day-border-hover`	--drp-accent-color
`--drp-day-drag-border`	2px dashed --drp-day-range-bg
`--drp-day-disabled-color`	--drp-text-secondary
`--drp-day-other-month-color`	--drp-text-secondary
`--drp-day-text-color`	--drp-text-primary
`--drp-day-today-border`	--drp-accent-color
`--drp-weekday-color`	--drp-text-secondary

Selection States

Variable	Default
`--drp-day-focused-outline`	--drp-accent-color
`--drp-day-focused-outline-width`	2px
`--drp-day-focused-outline-offset`	2px
`--drp-day-selected-bg`	--drp-accent-color
`--drp-day-selected-bg-hover`	--drp-accent-color-hover
`--drp-day-selected-color`	--drp-text-color-on-accent
`--drp-day-selected-color-hover`	--drp-day-selected-color
`--drp-day-disabled-bg`	transparent
`--drp-day-disabled-pattern-opacity`	0.1

Range States

Variable	Default
`--drp-day-range-bg`	--drp-accent-color
`--drp-day-range-bg-hover`	--drp-accent-color-hover
`--drp-day-range-color`	--drp-text-color-on-accent
`--drp-day-range-color-hover`	--drp-day-range-color
`--drp-day-in-range-bg-opacity`	0.15
`--drp-day-in-range-hover-bg-opacity`	0.25
Hover Preview (v1.13)
`--drp-day-hover-preview-bg-opacity`	0.18
`--drp-day-hover-preview-invalid-bg-opacity`	0.18
Drag & Invalid
`--drp-day-drag-preview-bg-opacity`	0.30
`--drp-day-drag-preview-edge-bg-opacity`	0.60
`--drp-day-dragging-scale`	1.1
`--drp-day-drag-invalid-bg`	#ef4444
`--drp-day-drag-invalid-bg-opacity`	0.20
`--drp-day-invalid-range-bg`	--drp-message-error-border
`--drp-day-invalid-range-color`	--drp-text-color-on-accent

Header & Navigation Variables

Header, navigation buttons, and rolling selector

Header

Variable	Default
`--drp-header-bg-active`	--drp-primary-bg-hover
`--drp-header-bg-hover`	--drp-primary-bg
`--drp-header-text-color`	--drp-text-primary
`--drp-unified-month-color`	--drp-text-secondary
`--drp-unified-range-bg-hover`	--drp-primary-bg
`--drp-unified-range-text-color`	--drp-text-primary

Navigation Buttons

Variable	Default
`--drp-nav-bg-active`	--drp-primary-bg-hover
`--drp-nav-bg-hover`	--drp-primary-bg
`--drp-nav-border-color`	--drp-border-color
`--drp-nav-border-hover`	--drp-accent-color
`--drp-nav-text-color`	--drp-text-primary

Rolling Selector

Variable	Default
`--drp-rolling-bg`	--drp-primary-bg
`--drp-rolling-border-color`	--drp-border-color
`--drp-rolling-item-bg-hover`	--drp-primary-bg
`--drp-rolling-item-bg-selected`	--drp-accent-color
`--drp-rolling-item-color-selected`	--drp-text-color-on-accent

Button & Summary Variables

Action buttons and summary section

Button States

Variable	Default
`--drp-button-bg`	transparent
`--drp-button-color`	--drp-text-primary
`--drp-button-bg-hover`	--drp-primary-bg
`--drp-button-border`	--drp-border
`--drp-button-border-color`	--drp-border-color
`--drp-button-border-hover`	--drp-accent-color

Button Types

Variable	Default
`--drp-button-apply-bg`	--drp-accent-color
`--drp-button-apply-bg-hover`	--drp-accent-color-hover
`--drp-button-apply-color`	white
`--drp-button-cancel-color`	--drp-text-secondary
`--drp-button-clear-color`	--drp-text-secondary
`--drp-button-today-color`	--drp-accent-color

Summary

Variable	Default
`--drp-summary-border`	--drp-border
`--drp-summary-border-color`	--drp-border-color
`--drp-summary-count-color`	--drp-accent-color
`--drp-summary-text-color`	--drp-text-secondary

Badge Variables

Badge styling for special dates

Badge Types

Variable	Default	Description
`--drp-badge-number-bg`	--drp-accent-color	Number badge background
`--drp-badge-number-color`	--drp-text-color-on-accent	Number badge text
`--drp-badge-count-bg`	#ef4444	Count badge background
`--drp-badge-count-color`	#ffffff	Count badge text
`--drp-badge-text-bg`	--drp-text-secondary	Text badge background
`--drp-badge-text-color`	#ffffff	Text badge text
`--drp-badge-row-height`	16px	Badge row height

Controls

Description

Loading & Tooltip Variables

Loading overlay and tooltip styling

Loading Overlay

Variable	Default
`--drp-loading-overlay-bg`	rgba(255, 255, 255, 0.8)
`--drp-loading-spinner-color`	--drp-border-color
`--drp-loading-spinner-accent`	--drp-accent-color
`--drp-loading-spinner-size`	40px
`--drp-loading-spinner-border-width`	4px

Tooltip

Variable	Default
`--drp-tooltip-bg`	#1f2937
`--drp-tooltip-text-color`	#ffffff
`--drp-tooltip-line-height`	1.4
`--drp-tooltip-max-width`	200px
`--drp-tooltip-arrow-size`	8px

Description

Modal Mode Variables

Centered overlay with backdrop (v1.12 — positioning-mode='modal')

Sizing & Backdrop

Variable	Default
`--drp-modal-gap`	16px
`--drp-modal-backdrop-bg`	rgba(0, 0, 0, 0.45)
`--drp-modal-transition`	150ms ease-out

Per-Tier Widths

Variable	Default	Viewport
`--drp-modal-width-xs`	calc(100vw − 2× gap)	≤ 480px
`--drp-modal-width-sm`	calc(100vw − 2× gap)	481–768px
`--drp-modal-width-md`	900px	769–1200px
`--drp-modal-width-lg`	1100px	≥ 1201px

Description

Message Variables

Inline message overlay colors (error / warning / info / success)

Error & Warning

Variable	Default
`--drp-message-error-bg`	#fef2f2
`--drp-message-error-color`	#991b1b
`--drp-message-error-border`	#fecaca
`--drp-message-warning-bg`	#fffbeb
`--drp-message-warning-color`	#92400e
`--drp-message-warning-border`	#fde68a

Info & Success

Variable	Default
`--drp-message-info-bg`	#eff6ff
`--drp-message-info-color`	#1e40af
`--drp-message-info-border`	#bfdbfe
`--drp-message-success-bg`	#f0fdf4
`--drp-message-success-color`	#166534
`--drp-message-success-border`	#bbf7d0

Description

Layout, Z-Index & Opacity

Calendar dimensions, stacking layers, and opacity tokens

Calendar Dimensions

Variable	Default
`--drp-month-min-width`	280px
`--drp-month-min-width-inline`	250px
`--drp-calendar-max-width`	calc(100vw − 2rem)
`--drp-grid-columns`	3
`--drp-grid-rows`	2

Z-Index Layers

Variable	Default
`--drp-z-index-dropdown`	9500
`--drp-z-index-modal-backdrop`	9700
`--drp-z-index-modal`	9800
`--drp-z-index-tooltip`	9999

Opacity Tokens

Variable	Default
`--drp-opacity-disabled`	0.6
`--drp-opacity-other-month`	0.5
`--drp-opacity-hover`	0.8
`--drp-opacity-dragging`	0.7

Weekend & Weekday Hooks (v1.13)

No defaults shipped — pure theming surface for weekend / per-day styling

CSS Hooks

Every day cell carries a numeric weekday attribute and Sat/Sun get an additional modifier class. These have no shipped styling; they exist so you can target weekends or specific days from your own stylesheet (via customStylesCallback).

Selector	Matches
`.drp-date-picker__day--weekend`	Saturday and Sunday cells
`.drp-date-picker__day[data-weekday="0"]`	Sunday (matches `Date.prototype.getDay()` values 0–6)

// Highlight Sundays in red, Saturdays in dimmed text
el.customStylesCallback = () => `
  .drp-date-picker__day[data-weekday="0"] { color: #dc2626; }
  .drp-date-picker__day[data-weekday="6"] { color: #6b7280; }
`;