When selecting date ranges, disabled dates (weekends, holidays, blackout dates) may fall within the range. The `disabled-dates-handling` attribute controls how the picker behaves in these situations.

This feature is crucial for hotel bookings, equipment rentals, appointment scheduling, and any system where you need precise control over how disabled dates affect range selections.

The Five Handling Modes

Choose the right behavior for your use case

Mode Comparison
ModeVisual BehaviorEvent Data
'allow'Range spans over disabled datesdateRange, enabledDates[], disabledDates[]
'prevent'Cannot complete selection across disabled datesSelection blocked - no event
'block'Range snaps to last enabled date before gapdateRange (adjusted end date)
'split'Range spans disabled datesdateRanges[] (multiple ranges), dates[]
'individual'Range spans disabled datesdates[] (flat array of enabled dates)
When to Use
'allow' - Hotel Booking

Guest can select any range, system calculates billable nights excluding closed days.

'prevent' - Strict Scheduling

Cannot create appointments that cross blackout dates. Forces selection of valid period.

'block' - Equipment Rental

Rental must end before weekend. Selection automatically snaps to Friday.

'split' - Recurring Bookings

Book same room for multiple separate periods (e.g., weekdays only over two weeks).

'individual' - Cherry-Pick Dates

Select range, get individual valid dates for batch processing.

Behavior
Attribute

disabled-dates-handling="mode"

JavaScript Option

disabledDatesHandling: 'allow' | 'prevent' | 'block' | 'split' | 'individual'

Default

'allow'

Applies To

Range mode only. Single mode ignores this setting.

Mode: 'allow' (Default)

Allow ranges over disabled dates with breakdown

Live Demo

Try selecting Mon Jan 6 to Fri Jan 17 (includes 2 weekends)

Code Examples
HTML 
 
 
JavaScript 
 
 
 
Details
 
Behavior
 
  • Range selection spans over disabled dates normally
    •  
  • Disabled dates within range are visually highlighted (grayed out)
    •  
  • Event includes both enabledDates[] and disabledDates[] arrays
    •  
  • Helper methods: getTotalDays(), getEnabledDateCount()
 
Event Detail Properties
 
  • dateRange - Full range with start and end
    •  
  • enabledDates - Array of enabled Date objects
    •  
  • disabledDates - Array of disabled Date objects
    •  
  • getTotalDays() - Function returning total days in range
    •  
  • getEnabledDateCount() - Function returning count of enabled dates
 
Use Cases
 
  • Hotel bookings with closed days
    •  
  • Pricing based on actual available dates
    •  
  • Visual clarity: show full period with exceptions
 
Mode: 'prevent' (Default)
 
REJECTS selections that cross disabled dates - no event fires
 
Live Demo
  
Try selecting Mon Jan 6 to Mon Jan 13 - selection will be blocked at weekend
  
 
Code Examples
 
HTML 
 
 
 
JavaScript 
 
 
 
Details
 
Behavior: "No, you can't"
 
  • Selection is REJECTED if it would cross disabled dates
    •  
  • date-select event is NOT fired - selection fails silently
    •  
  • User must try again with a valid range
    •  
  • Most restrictive mode - no compromise
 
Event Detail
 
  • No event fires when selection blocked
    •  
  • Only fires for valid, contiguous enabled ranges
 
Key Point: This mode rejects the selection entirely. If you want the selection to succeed but be auto-corrected, use 'block' mode instead.
 
Use Cases
 
  • Strict rules: Cannot book across closed periods (no exceptions)
    •  
  • Compliance: Must enforce contiguous dates
    •  
  • Critical resources: Equipment must be available entire period
 
User Experience
 
Selection attempt fails. User must manually select a different range that doesn't cross disabled dates. Enable show-debug-info to see console messages.
 
Mode: 'block'
 
ACCEPTS selection but AUTO-SHORTENS to last enabled date - event fires
 
Live Demo
  
Try selecting Mon Jan 6 to Mon Jan 13 - end date will snap to Fri Jan 10
  
 
Code Examples
 
HTML 
 
 
 
JavaScript 
 
 
 
Details
 
Behavior: "Yes, but shorter"
 
  • Selection is ACCEPTED but MODIFIED
    •  
  • End date automatically snaps to last enabled date before disabled gap
    •  
  • date-select event DOES fire with adjusted range
    •  
  • User gets a valid result (shorter than attempted)
 
Event Detail Properties
 
  • dateRange - Range with adjusted/shortened end date
    •  
  • All dates in returned range are enabled (no gaps)
    •  
  • No disabledDates array (none in range)
 
Key Difference from 'prevent': This mode accepts and adjusts the selection instead of rejecting it. Better UX when you want to help the user rather than block them.
 
Use Cases
 
  • Helpful UX: Auto-correct instead of rejecting
    •  
  • Equipment rental: Must return before weekend (auto-shorten)
    •  
  • Office booking: Ends on last work day
    •  
  • Cutoff dates: Availability ends at specific date
 
User Experience
 
User sees range visually snap back to last enabled date. Selection succeeds with clear feedback that it was adjusted.
 
Mode: 'split'
 
Return multiple ranges split by disabled dates
 
Live Demo
  
Try selecting Mon Jan 6 to Fri Jan 17 - splits into 2 week ranges
  
 
Code Examples
 
HTML 
 
 
 
JavaScript 
 
 
 
Details
 
Behavior
 
  • Range selection spans over disabled dates visually
    •  
  • On select, range is split into multiple contiguous ranges
    •  
  • Each sub-range contains only enabled dates
    •  
  • Event includes dateRanges[] array and dates[] array
 
Event Detail Properties
 
  • dateRange - Original full range (start to end)
    •  
  • dateRanges - Array of sub-ranges (each with start and end)
    •  
  • dates - Flat array of all enabled Date objects
    •  
  • formattedValue - Multiple ranges formatted (comma-separated)
 
Use Cases
 
  • Recurring bookings: same resource for weekdays over multiple weeks
    •  
  • Multi-period contracts: separate billing for each period
    •  
  • Batch processing: process each contiguous period separately
 
Example Scenario
 
User selects Mon Jan 6 to Fri Jan 17 with weekends disabled:
 
  • Range 1: Mon Jan 6 - Fri Jan 10 (5 days)
    •  
  • Range 2: Mon Jan 13 - Fri Jan 17 (5 days)
    •  
  • Total: 2 ranges, 10 enabled dates
 
Mode: 'individual'
 
Return flat array of individual enabled dates
 
Live Demo
  
Try selecting Mon Jan 6 to Fri Jan 17 - returns 10 individual dates
  
 
Code Examples
 
HTML 
 
 
 
JavaScript 
 
 
 
Details
 
Behavior
 
  • Range selection spans over disabled dates visually
    •  
  • On select, only enabled dates are returned
    •  
  • No range object or sub-ranges - just flat array
    •  
  • Event includes dates[] array only
 
Event Detail Properties
 
  • dates - Flat array of enabled Date objects
    •  
  • formattedValue - Comma-separated list of dates
    •  
  • dateRange - null (not provided)
 
Use Cases
 
  • Batch operations: process each date independently
    •  
  • Email scheduling: send on specific enabled dates
    •  
  • Report generation: one report per enabled date
    •  
  • Task assignment: assign task to each enabled day
 
Difference from 'split'
 
'split' returns ranges: [start: Mon, end: Fri, start: Mon, end: Fri]
 
'individual' returns dates: [Mon, Tue, Wed, Thu, Fri, Mon, Tue, ...]
 
Use 'individual' when you don't care about contiguity, just want the list of dates.
 
Visual Highlighting
 
Control disabled date highlighting in ranges
 
highlight-disabled-in-range
 
With Highlighting (default)
 
 
Without Highlighting
 
 
Select same range in both - notice disabled dates within range
 
Code Examples
 
HTML 
 
 
 
JavaScript 
 
 
 
Details
 
Attribute
 
highlight-disabled-in-range="true|false"
 
JavaScript Option
 
highlightDisabledInRange: boolean
 
Default
 
true
 
Behavior
 
  • true: Disabled dates within range get special styling (grayed out)
    •  
  • false: Only enabled dates within range are visually highlighted
 
Works With
 
All disabled handling modes. Most useful with 'allow' mode to show which dates are excluded from billing.
 
Use Cases
 
  • true: Hotel booking - clearly show non-billable closed days
    •  
  • false: Simplified view - only highlight valid dates
 
Decision Guide
 
Choose the right mode for your use case
 
Use Case
 
ScenarioMode
Hotel booking - bill for enabled nights only'allow'
Equipment rental - must return before weekend'block'
Appointment scheduling - cannot cross blackout dates'prevent'
Recurring meeting - weekdays only for 2 weeks'split'
Email blast - send on each enabled date'individual'
 
Recommended Mode
 
Question Flow
 
  1. Can user select across disabled dates? 
    • No → 'prevent' or 'block'
      •  
    • Yes → Continue
    2.  
  2. Do you need to know what was disabled? 
    • Yes → 'allow'
      •  
    • No → Continue
    3.  
  3. Are disabled dates gaps or just filters? 
    • Gaps creating separate periods → 'split'
      •  
    • Just filtering to valid dates → 'individual'
 
Why
 
Quick Reference
 
  • 'allow' - Need breakdown of enabled vs disabled
    •  
  • 'prevent' - Strict: no crossing disabled dates
    •  
  • 'block' - Auto-snap to valid range
    •  
  • 'split' - Multiple separate valid periods
    •  
  • 'individual' - Flat list of valid dates
 
Performance Note
 
All modes have similar performance. Choose based on business logic, not performance.
 
Troubleshooting
 
 
Check if you're using disabled-dates-handling="prevent". This mode blocks event firing if the range crosses disabled dates.
 
Enable show-debug-info to see console messages about prevented selections.
 
 
Use the helper functions in event detail:
 
 
 
 
 
'split' preserves range structure: dateRanges: [start, end, start, end]
 
'individual' flattens to dates: dates: [Date, Date, Date, ...]
 
Use 'split' when periods matter (e.g., separate invoices). Use 'individual' for batch operations where order doesn't matter.
 
 
Yes, update the attribute:
 
picker.setAttribute('disabled-dates-handling', 'block');
 
The picker will re-initialize automatically.
 
 
No, disabled-dates-handling only applies to range mode. In single mode, users simply cannot select disabled dates.