API Methods — keen_web

1. Show/Hide/Toggle Methods

Control calendar visibility programmatically. These methods are useful for external triggers, keyboard shortcuts, or conditional UI flows.

JS methods: el.show() · el.hide() · el.toggle()

Calendar state: closed

const picker = document.getElementById('picker-1');

picker.show();    // Show calendar
picker.hide();    // Hide calendar
picker.toggle();  // Toggle calendar

picker.addEventListener('calendar-open', () => console.log('Calendar opened'));
picker.addEventListener('calendar-close', () => console.log('Calendar closed'));

// Tip: add data-calendar-button to external trigger buttons to prevent
// "click outside" from closing the calendar.

void show()

void hide()

void toggle()

2. Get/Set Input Value

Read and write the formatted input value. The format follows the date-format-mask attribute. For range mode, use " - " separator (space-dash-space).

JS: el.getInputValue() · el.setInputValue(v)

Single Date (YYYY-MM-DD)

Date Range (MM/DD/YYYY)

Click buttons to get/set values...

const singlePicker = document.getElementById('picker-2a');
const rangePicker = document.getElementById('picker-2b');

const singleValue = singlePicker.getInputValue(); // "2025-03-15" or ""
const rangeValue = rangePicker.getInputValue();   // "01/01/2025 - 01/31/2025" or ""

singlePicker.setInputValue('2025-03-15');
rangePicker.setInputValue('01/01/2025 - 01/31/2025');

singlePicker.setInputValue(''); // clear

string getInputValue()

void setInputValue(value: string)

3. Clear Selection

Clear the current selection and reset the picker to its initial state. This clears both the input value and internal date state.

JS: el.clearSelection()

Selections will be cleared...

const picker = document.getElementById('picker-3a');

picker.clearSelection();
console.log(picker.getInputValue()); // ""

picker.clearSelection();
picker.setInputValue('2025-12-25');

void clearSelection()

4. Reactive Properties (selectedDate, selectedRanges)

Access and modify selection using Date objects. These properties are reactive and trigger re-rendering and events when changed.

JS props: el.selectedDate · el.selectedRanges

Single Mode

Range Mode

Click buttons to interact with reactive properties...

const singlePicker = document.getElementById('picker-4a');
const rangePicker = document.getElementById('picker-4b');

const date = singlePicker.selectedDate;        // Date | null
singlePicker.selectedDate = new Date('2025-12-25');

const ranges = rangePicker.selectedRanges;     // [{start, end}] | []
rangePicker.selectedRanges = [{
  start: new Date('2025-01-01'),
  end: new Date('2025-01-31')
}];

singlePicker.selectedDate = null;
rangePicker.selectedRanges = [];

Date | null selectedDate

DateRange[] selectedRanges

5. Calendar State (isOpen)

Read the current calendar visibility state. This is useful for conditional logic, UI synchronization, or analytics tracking.

JS prop (read-only): el.isOpen

Calendar state: unknown

const picker = document.getElementById('picker-5');

if (picker.isOpen) console.log('Calendar is visible');
else console.log('Calendar is hidden');

function smartToggle() {
  if (picker.isOpen) picker.hide();
  else picker.show();
}

picker.addEventListener('calendar-open', () => console.log('isOpen is now:', picker.isOpen));
picker.addEventListener('calendar-close', () => console.log('isOpen is now:', picker.isOpen));

boolean isOpen (read-only)

6. Picker Instance Access

Access the underlying DateRangePicker instance for advanced features and internal state. Note: This is an advanced API - prefer using web component methods when possible.

JS prop (read-only): el.picker — the underlying DateRangePicker

Click buttons to explore picker instance...

const component = document.getElementById('picker-6');
const picker = component.picker;

if (picker) {
  console.log('Selected start:', picker.selectedStartDate);
  console.log('Selected end:', picker.selectedEndDate);
  console.log('Format info:', picker.formatInfo);
  console.log('Mode:', picker.options.selectionMode);
  console.log('Months to show:', picker.options.visibleMonthsCount);
} else {
  console.warn('Picker not initialized yet');
}

DateRangePicker | null picker (read-only)

⚠️ Advanced API Warning:

Direct picker instance access is provided for advanced use cases. Modifying internal state directly may cause unexpected behavior. Always prefer web component methods and properties when available.

7. Complete API Reference

Full reference of all public methods, properties, and events available on the <web-daterangepicker> component.

Methods

Method	Returns	Description
`show()`	`void`	Open the calendar popup
`hide()`	`void`	Close the calendar popup
`toggle()`	`void`	Toggle calendar visibility
`getInputValue()`	`string`	Get formatted input value
`setInputValue(value)`	`void`	Set formatted input value
`clearSelection()`	`void`	Clear selection and reset state
`setMonthNames(names)`	`void`	Set custom month names array

Properties

Property	Type	Access	Description
`value`	`string`	Read/Write	Formatted input value (alias for get/setInputValue)
`disabled`	`boolean`	Read/Write	Disabled state of the picker
`selectedDate`	`Date \| null`	Read/Write	Selected date (single mode)
`selectedRanges`	`DateRange[]`	Read/Write	Selected ranges (range mode)
`selectedDates`	`Date[]`	Read/Write	Selected dates (multiple mode)
`isOpen`	`boolean`	Read/Write	Calendar visibility state
`selectionMode`	`'single' \| 'range'`	Read/Write	Selection mode
`dateFormatMask`	`string`	Read/Write	Date format mask (e.g., 'YYYY-MM-DD')
`minDate`	`string \| undefined`	Read/Write	Minimum selectable date
`maxDate`	`string \| undefined`	Read/Write	Maximum selectable date
`specialDates`	`DecoratedDate[]`	Read/Write	Array of dates with badges/tooltips
`disabledDates`	`(Date \| string)[]`	Read/Write	Array of disabled dates
`picker`	`DateRangePicker \| null`	Read-only	Underlying picker instance (advanced)

Events

Event	Detail Type	Description
`date-select`	`DateSelectDetail`	Fired when date(s) selected
`change`	`DateSelectDetail`	Alias for date-select (same detail)
`calendar-open`	`void`	Fired when calendar opens
`calendar-close`	`void`	Fired when calendar closes
`input-change`	`string`	Fired when input value changes (typing)

TypeScript Interfaces

interface DateRange { start: Date; end: Date; }

interface DateSelectDetail {
  formattedValue: string;
  date?: Date;           // Single mode only
  dateRange?: DateRange; // Range mode only
}

const picker = document.getElementById('my-picker') as WebDaterangepickerElement;

picker.addEventListener('date-select', (event: CustomEvent<DateSelectDetail>) => {
  console.log('Formatted:', event.detail.formattedValue);
  if (event.detail.date) console.log('Single date:', event.detail.date);
  if (event.detail.dateRange) console.log('Range:', event.detail.dateRange.start, '-', event.detail.dateRange.end);
});

8. Integration Patterns

Common patterns for integrating the date picker with forms, frameworks, and application state.

Form Integration

<form id="booking-form">
  <web-daterangepicker id="check-in" name="check-in-date" selection-mode="single" required></web-daterangepicker>
  <button type="submit">Book Now</button>
</form>

<script>
const form = document.getElementById('booking-form');
const checkIn = document.getElementById('check-in');

form.addEventListener('submit', (e) => {
  e.preventDefault();
  const date = checkIn.selectedDate;
  if (!date) { alert('Please select a check-in date'); return; }
  const formData = new FormData();
  formData.append('check-in', checkIn.getInputValue());
  fetch('/api/booking', { method: 'POST', body: formData });
});
</script>

React/Vue Integration

// React
import { useRef, useEffect } from 'react';

function DatePicker({ value, onChange }) {
  const pickerRef = useRef(null);
  useEffect(() => {
    const picker = pickerRef.current;
    const handleSelect = (e) => onChange(e.detail.formattedValue);
    picker.addEventListener('date-select', handleSelect);
    return () => picker.removeEventListener('date-select', handleSelect);
  }, [onChange]);
  useEffect(() => {
    if (pickerRef.current && value) pickerRef.current.setInputValue(value);
  }, [value]);
  return <web-daterangepicker ref={pickerRef} />;
}

// Vue 3
<template>
  <web-daterangepicker ref="picker" @date-select="handleSelect"></web-daterangepicker>
</template>

State Synchronization

// Synchronize with application state
class DateRangeManager {
  constructor() {
    this.picker = document.getElementById('date-range');
    this.state = { start: null, end: null, formatted: '' };
    this.init();
  }
  init() {
    this.picker.addEventListener('date-select', (e) => {
      if (e.detail.dateRange) {
        this.state.start = e.detail.dateRange.start;
        this.state.end = e.detail.dateRange.end;
        this.state.formatted = e.detail.formattedValue;
        this.onStateChange();
      }
    });
    this.restoreState();
  }
  onStateChange() {
    localStorage.setItem('date-range', JSON.stringify({
      start: this.state.start?.toISOString(),
      end: this.state.end?.toISOString()
    }));
  }
  restoreState() {
    const saved = localStorage.getItem('date-range');
    if (saved) {
      const { start, end } = JSON.parse(saved);
      this.picker.selectedRanges = [{ start: new Date(start), end: new Date(end) }];
    }
  }
}

const manager = new DateRangeManager();