or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdconstructor-api.mdevents.mdindex.mdinstance-methods.mdjquery-plugin.mdlocalization.md
tile.json

events.mddocs/

Event System

Bootstrap DateRangePicker provides a comprehensive event system for responding to picker state changes and user interactions. All events are namespaced with .daterangepicker.

Capabilities

Event Names and Triggers

Complete list of events triggered by the DateRangePicker during its lifecycle.

// Core visibility events
'show.daterangepicker'        // Triggered when picker dropdown is shown
'hide.daterangepicker'        // Triggered when picker dropdown is hidden

// Calendar display events
'showCalendar.daterangepicker'  // Triggered when calendar view is shown
'hideCalendar.daterangepicker'  // Triggered when calendar view is hidden

// User interaction events
'apply.daterangepicker'       // Triggered when user applies date selection
'cancel.daterangepicker'      // Triggered when user cancels date selection
'outsideClick.daterangepicker'  // Triggered when user clicks outside picker

Event Handler Registration

Events can be bound using jQuery's standard event handling methods.

// Using .on() method (recommended)
$('#daterange').on('apply.daterangepicker', function(ev, picker) {
  console.log('Date range applied:', picker.startDate.format('YYYY-MM-DD'), 'to', picker.endDate.format('YYYY-MM-DD'));
});

// Multiple event handlers
$('#daterange')
  .on('show.daterangepicker', function(ev, picker) {
    console.log('Picker opened');
  })
  .on('hide.daterangepicker', function(ev, picker) {
    console.log('Picker closed');
  })
  .on('apply.daterangepicker', function(ev, picker) {
    console.log('Date range selected');
  });

// Using event delegation for dynamically created elements
$(document).on('apply.daterangepicker', '.daterange-input', function(ev, picker) {
  console.log('Date range applied on element:', this.id);
});

Show/Hide Events

Events triggered when the picker dropdown becomes visible or hidden.

/**
 * show.daterangepicker - Triggered when picker dropdown is shown
 * @param {Event} ev - jQuery event object
 * @param {DateRangePicker} picker - DateRangePicker instance
 */
$('#daterange').on('show.daterangepicker', function(ev, picker) {
  console.log('Picker is now visible');
  console.log('Current date range:', picker.startDate.format('YYYY-MM-DD'), 'to', picker.endDate.format('YYYY-MM-DD'));
});

/**
 * hide.daterangepicker - Triggered when picker dropdown is hidden
 * @param {Event} ev - jQuery event object  
 * @param {DateRangePicker} picker - DateRangePicker instance
 */
$('#daterange').on('hide.daterangepicker', function(ev, picker) {
  console.log('Picker is now hidden');
});

Usage Examples:

// Track picker visibility for analytics
$('#daterange').on('show.daterangepicker', function(ev, picker) {
  analytics.track('daterange_picker_opened', {
    element_id: this.id,
    current_range: picker.startDate.format('YYYY-MM-DD') + ' to ' + picker.endDate.format('YYYY-MM-DD')
  });
});

// Auto-focus on show
$('#daterange').on('show.daterangepicker', function(ev, picker) {
  // Focus first input after picker opens
  setTimeout(function() {
    picker.container.find('input[name="daterangepicker_start"]').focus();
  }, 100);
});

// Cleanup on hide
$('#daterange').on('hide.daterangepicker', function(ev, picker) {
  // Clear any temporary validation messages
  $('.daterange-error').hide();
});

Calendar Display Events

Events triggered when calendar views are shown or hidden (typically when switching between predefined ranges and custom range selection).

/**
 * showCalendar.daterangepicker - Triggered when calendar view is shown
 * @param {Event} ev - jQuery event object
 * @param {DateRangePicker} picker - DateRangePicker instance
 */
$('#daterange').on('showCalendar.daterangepicker', function(ev, picker) {
  console.log('Calendar view is now visible');
});

/**
 * hideCalendar.daterangepicker - Triggered when calendar view is hidden
 * @param {Event} ev - jQuery event object
 * @param {DateRangePicker} picker - DateRangePicker instance  
 */
$('#daterange').on('hideCalendar.daterangepicker', function(ev, picker) {
  console.log('Calendar view is now hidden');
});

Usage Examples:

// Adjust picker height when calendar shows/hides
$('#daterange')
  .on('showCalendar.daterangepicker', function(ev, picker) {
    picker.container.addClass('calendar-visible');
  })
  .on('hideCalendar.daterangepicker', function(ev, picker) {
    picker.container.removeClass('calendar-visible');
  });

// Help text based on calendar visibility
$('#daterange')
  .on('showCalendar.daterangepicker', function(ev, picker) {
    $('#help-text').text('Select a custom date range using the calendars');
  })
  .on('hideCalendar.daterangepicker', function(ev, picker) {
    $('#help-text').text('Choose from predefined ranges or select Custom Range');
  });

User Interaction Events

Events triggered by user actions like applying or canceling date selections.

/**
 * apply.daterangepicker - Triggered when user applies date selection
 * @param {Event} ev - jQuery event object
 * @param {DateRangePicker} picker - DateRangePicker instance
 */
$('#daterange').on('apply.daterangepicker', function(ev, picker) {
  console.log('Date range applied:', picker.startDate.format('YYYY-MM-DD'), 'to', picker.endDate.format('YYYY-MM-DD'));
  console.log('Chosen label:', picker.chosenLabel);
});

/**
 * cancel.daterangepicker - Triggered when user cancels date selection
 * @param {Event} ev - jQuery event object
 * @param {DateRangePicker} picker - DateRangePicker instance
 */
$('#daterange').on('cancel.daterangepicker', function(ev, picker) {
  console.log('Date range selection cancelled');
});

/**
 * outsideClick.daterangepicker - Triggered when user clicks outside picker
 * @param {Event} ev - jQuery event object
 * @param {DateRangePicker} picker - DateRangePicker instance
 */
$('#daterange').on('outsideClick.daterangepicker', function(ev, picker) {
  console.log('User clicked outside picker');
});

Usage Examples:

// Form integration with apply event
$('#booking-form input[name="daterange"]').on('apply.daterangepicker', function(ev, picker) {
  // Update form fields
  $('#checkin-date').val(picker.startDate.format('YYYY-MM-DD'));
  $('#checkout-date').val(picker.endDate.format('YYYY-MM-DD'));
  
  // Trigger form validation
  $('#booking-form').trigger('validate');
  
  // Update UI
  $(this).val(picker.startDate.format('MM/DD/YYYY') + ' - ' + picker.endDate.format('MM/DD/YYYY'));
});

// AJAX request on date selection
$('#report-daterange').on('apply.daterangepicker', function(ev, picker) {
  $('#loading').show();
  
  $.ajax({
    url: '/api/reports',
    method: 'GET',
    data: {
      start_date: picker.startDate.format('YYYY-MM-DD'),
      end_date: picker.endDate.format('YYYY-MM-DD'),
      range_label: picker.chosenLabel
    },
    success: function(data) {
      $('#report-content').html(data);
      $('#loading').hide();
    },
    error: function() {
      alert('Failed to load report data');
      $('#loading').hide();
    }
  });
});

// Clear input on cancel
$('#daterange').on('cancel.daterangepicker', function(ev, picker) {
  if (picker.autoUpdateInput === false) {
    $(this).val(''); // Clear input if not auto-updating
  }
});

// Analytics tracking
$('#daterange').on('apply.daterangepicker', function(ev, picker) {
  analytics.track('date_range_selected', {
    start_date: picker.startDate.format('YYYY-MM-DD'),
    end_date: picker.endDate.format('YYYY-MM-DD'),
    range_label: picker.chosenLabel,
    range_days: picker.endDate.diff(picker.startDate, 'days') + 1
  });
});

Event Data and Properties

All event handlers receive the DateRangePicker instance as the second parameter, providing access to current state and configuration.

// Event handler receives picker instance
$('#daterange').on('apply.daterangepicker', function(ev, picker) {
  // Access current selection
  console.log('Start date:', picker.startDate.format('YYYY-MM-DD'));
  console.log('End date:', picker.endDate.format('YYYY-MM-DD'));
  console.log('Chosen label:', picker.chosenLabel);
  
  // Access configuration
  console.log('Auto apply:', picker.autoApply);
  console.log('Single date picker:', picker.singleDatePicker);
  console.log('Time picker:', picker.timePicker);
  
  // Access DOM elements
  console.log('Target element:', picker.element);
  console.log('Picker container:', picker.container);
  
  // Access state
  console.log('Is showing:', picker.isShowing);
});

Advanced Event Patterns

Conditional Event Handling:

$('#daterange').on('apply.daterangepicker', function(ev, picker) {
  // Different handling based on range selection
  if (picker.chosenLabel) {
    console.log('Predefined range selected:', picker.chosenLabel);
    // Handle predefined range
  } else {
    console.log('Custom range selected');
    // Handle custom range
  }
  
  // Validate date selection
  var daysDiff = picker.endDate.diff(picker.startDate, 'days');
  if (daysDiff > 90) {
    alert('Date range cannot exceed 90 days');
    return false; // Could prevent default behavior in some cases
  }
});

Event Namespacing for Multiple Handlers:

// Use additional namespaces to organize handlers
$('#daterange')
  .on('apply.daterangepicker.validation', function(ev, picker) {
    // Validation-specific handling
    return validateDateRange(picker.startDate, picker.endDate);
  })
  .on('apply.daterangepicker.ui', function(ev, picker) {
    // UI update handling
    updateDateRangeDisplay(picker.startDate, picker.endDate);
  })
  .on('apply.daterangepicker.analytics', function(ev, picker) {
    // Analytics tracking
    trackDateRangeSelection(picker);
  });

// Remove specific namespaced handlers
$('#daterange').off('apply.daterangepicker.analytics');

Event Prevention and Propagation:

$('#daterange').on('show.daterangepicker', function(ev, picker) {
  // Prevent showing under certain conditions
  if (!userCanModifyDates()) {
    ev.preventDefault();
    ev.stopPropagation();
    alert('You do not have permission to modify dates');
    return false;
  }
});