Button Configuration — keen_web

1. Button & Summary Visibility Control

is_today_button_shown={false} · is_clear_button_shown={false} · is_apply_button_shown={false} · is_summary_shown={false}

Use attributes to show/hide built-in buttons (Today, Clear, Apply) and the range-mode days/nights summary.

No Buttons (Manual Close Only) is-today-button-shown="false" is-clear-button-shown="false" is-apply-button-shown="false"

Only Clear Button is-today-button-shown="false" is-apply-button-shown="false"

Only Apply Button auto-close="apply" is-today-button-shown="false" is-clear-button-shown="false"

No Summary (Range Mode) is-summary-shown="false" — hides the days/nights count line entirely (no empty-div jump)

// HTML attributes control built-in button visibility
<web-daterangepicker
  is-today-button-shown="false"
  is-clear-button-shown="false"
  is-apply-button-shown="false">
</web-daterangepicker>

// Range mode: hide the days/nights summary block entirely
<web-daterangepicker selection-mode="range" is-summary-shown="false"></web-daterangepicker>

1b. Modal Display Mode (centered overlay)

positioning_mode="modal"

Set positioning-mode="modal" to render the calendar as a centered overlay with a backdrop scrim instead of anchoring to the input. Helpful on small screens where multi-month layouts horizontally overflow.

Single-month modal positioning-mode="modal" — click input or button to open

Multi-month modal (3 columns) visible-months-count="3" — would overflow horizontally on mobile in floating mode; in modal it fits and scrolls vertically

Grid modal (2×3) month-layout="grid" grid-rows="2" grid-columns="3" — six months in a centered grid

Auto-engage modal at small viewports positioning-mode="floating" mobile-modal-breakpoint="768px" mobile-modal-min-height="500px" — floating when there's enough room, modal when viewport is too narrow OR too short (resize the window to test)

// Centered overlay with backdrop — close via Apply, Escape, or backdrop click
<web-daterangepicker selection-mode="range" positioning-mode="modal"></web-daterangepicker>

// Open programmatically
document.querySelector('#picker').isOpen = true;

// CSS variables for theming
--drp-modal-gap: 16px;                     /* viewport-edge gap */
--drp-modal-backdrop-bg: rgba(0,0,0,0.45); /* scrim color */
--drp-modal-transition: 150ms ease-out;    /* fade timing */

2. Auto-Close Behavior

auto_close="never | selection | apply"

Control when the calendar automatically closes with the auto-close attribute.

auto-close="never" (Manual Close Only) Calendar NEVER auto-closes, not even with Apply button - user must close manually

auto-close="selection" (Auto-Close on Selection) - DEFAULT Closes when selection completes (click, drag-adjust). Note: Multiple mode never auto-closes

auto-close="apply" (Only Apply Closes) Only the Apply button closes the calendar

// Auto-close modes: 'never', 'selection' (default), 'apply'
<web-daterangepicker auto-close="never"></web-daterangepicker>
<web-daterangepicker auto-close="selection"></web-daterangepicker>
<web-daterangepicker auto-close="apply"></web-daterangepicker>

3. Custom Preset Buttons (JavaScript)

JS: el.actionButtons = [{ action: 'custom', text, onClick }]

Add custom buttons with preset date ranges using the JavaScript API.

Date Picker with Preset Shortcuts Buttons: Last Week, Next Week, Next Month

const picker = document.querySelector('#preset-picker');

picker.actionButtons = [
  { action: 'custom', text: 'Last Week', onClick: ({ picker }) => {
      const end = new Date(); const start = new Date();
      start.setDate(end.getDate() - 7);
      picker.selectedRanges = [{ start, end }];   // v2.0.0: start/end are read-only; set via selectedRanges
  } },
  { action: 'custom', text: 'Next Week', onClick: ({ picker }) => { /* ... */ } },
  { action: 'custom', text: 'Next Month', onClick: ({ picker }) => { /* ... */ } },
  { action: 'clear', text: 'Clear' },
  { action: 'apply', text: 'Apply' }
];

4. Multiple Selection Mode

selection_mode="multiple"

Allow selecting multiple individual dates or ranges programmatically.

Multiple Date Selection Click dates to toggle selection (selection-mode="multiple")

No selections yet

// Multiple mode: click dates to toggle selection
<web-daterangepicker selection-mode="multiple"></web-daterangepicker>

// Get selected dates/ranges
const dates = picker.selectedDates;    // Individual dates
const ranges = picker.selectedRanges;  // Date ranges

5. External Button Control (Programmatic API)

JS prop: el.selectedRanges = [{ start, end }]

Control the picker from external buttons using reactive properties.

Picker Controlled by External Buttons Use the buttons below to set ranges programmatically

No selection

const picker = document.querySelector('#external-picker');

// Set a single range programmatically
picker.selectedRanges = [{ start: new Date('2025-01-01'), end: new Date('2025-01-31') }];

// Set multiple ranges (for multiple mode)
picker.selectedRanges = [
  { start: new Date('2025-01-01'), end: new Date('2025-01-07') },
  { start: new Date('2025-01-15'), end: new Date('2025-01-21') }
];

// Control calendar visibility
picker.isOpen = true;
picker.isOpen = false;

6. Conditional Button Visibility (JavaScript)

JS: isVisibleCallback: (ctx) => boolean · ctx.picker is the instance

Show/hide buttons based on picker state using the isVisibleCallback function.

Context-Aware Buttons Apply button only shows when a range is selected (calendar stays open with auto-close="apply")

const picker = document.querySelector('#conditional-picker');

picker.actionButtons = [
  { action: 'today', text: 'Today' },
  { action: 'clear', text: 'Clear' },
  {
    action: 'apply', text: 'Apply',
    // Only show Apply when both dates are selected
    isVisibleCallback: ({ picker }) => picker.selectedStartDate && picker.selectedEndDate
  }
];

7. Dynamic Disabled State (isDisabledCallback)

JS: isDisabledCallback: (ctx) => boolean · ctx.picker is the instance

Enable/disable buttons dynamically based on picker state.

State-Aware Button Disabling Apply disabled until both dates selected, Clear disabled when no selection

const picker = document.querySelector('#disabled-picker');

picker.actionButtons = [
  { action: 'today', text: 'Today' },
  { action: 'clear', text: 'Clear',
    isDisabledCallback: ({ picker }) => !picker.selectedStartDate && !picker.selectedEndDate },
  { action: 'apply', text: 'Apply',
    isDisabledCallback: ({ picker }) => !picker.selectedStartDate || !picker.selectedEndDate }
];

8. Dynamic Button Text (getTextCallback)

JS: getTextCallback: (ctx) => string · ctx.picker is the instance

Change button text dynamically based on picker state.

Dynamic Text Updates Apply button shows day count, Clear shows what will be cleared

const picker = document.querySelector('#text-picker');

picker.actionButtons = [
  { action: 'today', text: 'Today' },
  { action: 'clear', text: 'Clear',
    getTextCallback: ({ picker }) => picker.selectedStartDate ? 'Clear Selection' : 'Clear' },
  { action: 'apply', text: 'Apply',
    getTextCallback: ({ picker }) => {
      if (!picker.selectedStartDate || !picker.selectedEndDate) return 'Apply';
      const days = Math.floor((picker.selectedEndDate - picker.selectedStartDate) / 86400000) + 1;
      return `Apply (${days} day${days !== 1 ? 's' : ''})`;
    } }
];

9. Dynamic CSS Classes (getClassCallback)

JS: getClassCallback: (ctx) => string | string[] · ctx.picker is the instance

Apply dynamic CSS classes to buttons based on picker state. Callback can return a single string or array of strings.

Dynamic Styling Apply button changes color based on completion, Clear button becomes red when selection exists

const picker = document.querySelector('#css-picker');

picker.actionButtons = [
  { action: 'today', text: 'Today' },
  { action: 'clear', text: 'Clear', cssClass: 'clear-button',
    getClassCallback: ({ picker }) => {
      const classes = ['clear-button'];
      if (picker.selectedStartDate || picker.selectedEndDate) classes.push('danger');
      return classes;
    } },
  { action: 'apply', text: 'Apply',
    getClassCallback: ({ picker }) =>
      (picker.selectedStartDate && picker.selectedEndDate) ? 'apply-ready' : 'apply-waiting' }
];

picker.customStylesCallback = () => `
  .apply-ready { background: #10b981 !important; color: white !important; }
  .apply-waiting { background: #d1d5db !important; color: #6b7280 !important; }
  .danger { background: #ef4444 !important; color: white !important; }
`;

10. Dynamic Tooltips (getTooltipCallback)

JS: getTooltipCallback: (ctx) => string · ctx.picker is the instance

Show contextual tooltips that change based on picker state. Hover over buttons to see dynamic tooltips.

Context-Aware Tooltips Tooltips update based on selection state and provide helpful context

const picker = document.querySelector('#tooltip-picker');

picker.actionButtons = [
  { action: 'today', text: 'Today', tooltip: 'Jump to today',
    getTooltipCallback: ({ picker }) => `Set to ${new Date().toLocaleDateString()}` },
  { action: 'clear', text: 'Clear', tooltip: 'Clear selection',
    getTooltipCallback: ({ picker }) =>
      (!picker.selectedStartDate && !picker.selectedEndDate)
        ? 'No selection to clear' : 'Clear the current date range' },
  { action: 'apply', text: 'Apply',
    getTooltipCallback: ({ picker }) => {
      if (!picker.selectedStartDate || !picker.selectedEndDate) return 'Select both start and end dates';
      const days = Math.floor((picker.selectedEndDate - picker.selectedStartDate) / 86400000) + 1;
      return `Apply ${days}-day range`;
    } }
];

11. Combined Features & Priority System

Demonstrates callback priority: *Callback functions override static properties when both are present.

Priority Chain:
• Visibility: isVisibleCallback → isVisible → true
• Disabled: isDisabledCallback → isDisabled → false
• Text: getTextCallback → text → action
• Class: getClassCallback → cssClass → ''
• Tooltip: getTooltipCallback → tooltip → ''

All Features Combined Clear button uses all callbacks simultaneously, demonstrating callback priority

const picker = document.querySelector('#priority-picker');

picker.actionButtons = [
  { action: 'today', text: 'Today' },
  {
    action: 'clear',
    text: 'Clear All',           // Overridden by getTextCallback
    cssClass: 'base-clear',      // Overridden by getClassCallback
    tooltip: 'Static tooltip',   // Overridden by getTooltipCallback
    isVisible: true,             // Overridden by isVisibleCallback
    isDisabled: false,           // Overridden by isDisabledCallback
    isVisibleCallback: ({ picker: p }) => p.selectedStartDate || p.selectedEndDate,
    isDisabledCallback: ({ picker: p }) => !p.selectedStartDate && !p.selectedEndDate,
    getTextCallback: ({ picker: p }) => (p.selectedStartDate || p.selectedEndDate) ? 'Clear Selection' : 'Clear All',
    getClassCallback: ({ picker: p }) => (p.selectedStartDate || p.selectedEndDate) ? 'danger' : 'base-clear',
    getTooltipCallback: ({ picker: p }) => (!p.selectedStartDate && !p.selectedEndDate) ? 'Nothing to clear' : 'Remove current selection'
  }
];

12. Advanced Custom Actions (Business Use Cases)

Real-world examples of custom buttons for common business scenarios.

Business Period Presets Quick access to fiscal quarters, business weeks, and rolling periods

const picker = document.querySelector('#advanced-picker');

picker.actionButtons = [
  { action: 'custom', text: 'Last Business Week', tooltip: 'Select Monday-Friday of last week',
    onClick: ({ picker }) => { /* set Mon-Fri of last week */ } },
  { action: 'custom', text: 'This Quarter', tooltip: 'Select current fiscal quarter',
    onClick: ({ picker }) => { /* set current quarter */ } },
  { action: 'custom', text: 'Year to Date', tooltip: 'From Jan 1 to today',
    onClick: ({ picker }) => { /* set Jan 1 → today */ } },
  { action: 'custom', text: 'Rolling 90 Days', cssClass: 'rolling-period',
    onClick: ({ picker }) => { /* set today-89 → today */ } },
  { action: 'clear', text: 'Clear' },
  { action: 'apply', text: 'Apply' }
];

13. Icons in Buttons (Font Awesome)

Add icons to buttons using HTML in the text property. Works with Font Awesome, Material Icons, or any icon library.

Note: Since the calendar uses Shadow DOM, you must import Font Awesome inside the shadow root using @import in customStylesCallback. The text property accepts HTML, allowing you to include <i> or <svg> elements.

Buttons with Icons Visual enhancement using Font Awesome icons

const picker = document.querySelector('#icon-picker');

picker.actionButtons = [
  { action: 'today', text: '<i class="fa-solid fa-calendar-day"></i> Today', tooltip: 'Jump to today' },
  { action: 'clear', text: '<i class="fa-solid fa-circle-xmark"></i> Clear', cssClass: 'danger-icon' },
  { action: 'apply', text: '<i class="fa-solid fa-circle-check"></i> Apply', cssClass: 'success-icon' }
];

// Import Font Awesome into Shadow DOM and style buttons
picker.customStylesCallback = () => `
  @import url('https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css');
  .drp__action { display: inline-flex; align-items: center; gap: 0.375rem; }
  .success-icon { background: #10b981 !important; color: white !important; }
  .danger-icon { background: #ef4444 !important; color: white !important; }
`;

14. ActionButton API Reference

Complete reference for all ActionButton interface properties.

Core Properties

Property	Type	Required	Description
`action`	`'today' \| 'clear' \| 'apply' \| 'custom'`	✓	Button action type. Use 'custom' for custom onClick handlers.
`text`	`string`	✓	Button label (supports HTML for icons).
`onClick`	`(picker) => void`		Custom click handler (required for action: 'custom').

Dynamic Callbacks (Override Static Properties)

Property	Type	Description
`isVisibleCallback`	`(picker) => boolean`	Dynamic visibility control based on picker state.
`isDisabledCallback`	`(picker) => boolean`	Dynamic disabled state based on picker state.
`getTextCallback`	`(picker) => string`	Dynamic button text based on picker state.
`getClassCallback`	`(picker) => string \| string[]`	Dynamic CSS classes (single string or array).
`getTooltipCallback`	`(picker) => string`	Dynamic tooltip text based on picker state.

Priority System

When both static properties and callbacks are defined, callbacks take priority:

// Callback priority chain:
isVisibleCallback → isVisible → true
isDisabledCallback → isDisabled → false
getTextCallback → text → action
getClassCallback → cssClass → ''
getTooltipCallback → tooltip → ''