Date Picker

Date pickers display a month grid for selecting a single date or a date range inline. Use them when dates need to remain visible, such as in scheduling interfaces or embedded inside another form control.

Date pickers display an inline calendar that lets users choose a single date or a date range. They follow the WAI-ARIA Date Picker pattern and use Intl.DateTimeFormat for localization.

<wa-date-picker style="max-width: 300px;"></wa-date-picker>

Examples

Initial Value

By default, the calendar is in single-date mode. Set the value attribute to an ISO date string (YYYY-MM-DD) to preselect a date.

<wa-date-picker style="max-width: 300px;" value="2026-05-11"></wa-date-picker>

The value attribute always uses ISO 8601 date-only strings: YYYY-MM-DD for single dates and YYYY-MM-DD/YYYY-MM-DD for ranges. The JavaScript setter also accepts Date objects and { from, to } shapes for ergonomic use in code.

<script type="module">
  const picker = document.querySelector('wa-date-picker');

  // Strings
  picker.value = '2026-05-11';
  picker.value = '2026-05-11/2026-05-18';

  // Date objects (single mode)
  picker.value = new Date(2026, 4, 11);

  // Range objects
  picker.value = { from: '2026-05-11', to: '2026-05-18' };
  picker.value = { from: new Date(2026, 4, 11), to: new Date(2026, 4, 18) };
</script>

Read the value back with the read-only valueAsDate and valueAsRange properties for typed access.

<script type="module">
  const picker = document.querySelector('wa-date-picker');

  // mode="single"
  const date = picker.valueAsDate; // Date | null

  // mode="range"
  const { from, to } = picker.valueAsRange; // { from: Date | null; to: Date | null }
</script>

Min & Max

Use min and max to bound the selectable range. Days outside the bounds are disabled and not focusable.

<wa-date-picker style="max-width: 300px;" min="2026-05-08" max="2026-05-22" value="2026-05-15"></wa-date-picker>

Disabling Past & Future

Use disable-past or disable-future to disable all dates before or after today. These are convenience shortcuts that don't require knowing today's date in advance.

<wa-date-picker style="max-width: 300px;" disable-past></wa-date-picker>

<wa-date-picker style="max-width: 300px;" disable-future></wa-date-picker>

Date Range

Use mode="range" to let users pick a start and end date. In range mode, the value is two ISO dates separated by a forward slash, e.g. 2026-05-11/2026-05-18.

<wa-date-picker style="max-width: 600px;" mode="range" months="2" value="2026-05-11/2026-05-18"></wa-date-picker>

Two-Month Display

Set months="2" to render two months side-by-side. This is especially useful in range mode so users can see both ends of a long range at once.

<wa-date-picker style="max-width: 600px;" mode="range" months="2"></wa-date-picker>

By default, the previous/next buttons advance the visible range by two months. Set page-by="single" to advance one month at a time instead.

<wa-date-picker style="max-width: 600px;" months="2" page-by="single"></wa-date-picker>

Size

Use the size attribute to set the calendar's size.

<wa-date-picker style="max-width: 300px;" size="s"></wa-date-picker>

<wa-date-picker style="max-width: 300px;" size="m"></wa-date-picker>

<wa-date-picker style="max-width: 300px;" size="l"></wa-date-picker>

Disabled

Use the disabled attribute to disable the entire calendar.

<wa-date-picker style="max-width: 300px;" disabled value="2026-05-11"></wa-date-picker>

Readonly

Use the readonly attribute to display the current value without allowing changes. Cells remain focusable so users can still navigate the grid with the keyboard.

<wa-date-picker style="max-width: 300px;" readonly value="2026-05-11"></wa-date-picker>

Disabling Specific Dates

Use disabled-dates with a whitespace-separated list of ISO dates to disable individual days. This is useful for holidays or blackout dates. Whitespace around each date is trimmed, so you can put dates on separate lines for readability.

<wa-date-picker
  style="max-width: 300px;"
  value="2026-05-11"
  disabled-dates="
    2026-05-25
    2026-05-26
    2026-07-04
  "
></wa-date-picker>

Disabling Days of the Week

Use disabled-days-of-week to disable specific weekdays. The attribute accepts a space-separated list of three-letter weekday names (sun, mon, tue, wed, thu, fri, sat), in any order.

<wa-date-picker style="max-width: 300px;" disabled-days-of-week="sun sat"></wa-date-picker>

<wa-date-picker style="max-width: 300px;" disabled-days-of-week="mon wed fri"></wa-date-picker>

Range Length Constraints

Use min-range and max-range to enforce a minimum or maximum range length in days. If the user's second click violates the constraint, the range is not committed.

<wa-date-picker style="max-width: 600px;" mode="range" months="2" min-range="3" max-range="14"></wa-date-picker>

Localization

Set the locale attribute to a BCP-47 language tag. When omitted, the calendar uses the inherited lang attribute. Month and weekday names, the first day of the week, and weekend designations are all locale-aware.

<wa-date-picker style="max-width: 300px;" locale="es"></wa-date-picker> <br /><br />
<wa-date-picker style="max-width: 300px;" locale="ko"></wa-date-picker>

First Day of the Week

By default, the first day of the week is determined by the locale. Set first-day-of-week to a three-letter weekday name (sun, mon, tue, wed, thu, fri, or sat) to override.

<wa-date-picker style="max-width: 300px;" first-day-of-week="mon"></wa-date-picker>

Weekday Format

Use weekday-format to control how weekday headers are rendered.

<wa-date-picker style="max-width: 300px;" weekday-format="narrow"></wa-date-picker>

<wa-date-picker style="max-width: 300px;" weekday-format="short"></wa-date-picker>

<wa-date-picker style="max-width: 300px;" weekday-format="long"></wa-date-picker>

Week Numbers

Use with-week-numbers to display ISO 8601 week numbers in a column on the left.

<wa-date-picker style="max-width: 300px;" with-week-numbers></wa-date-picker>

Outside Days

Use with-outside-days to render the trailing days of the previous month and the leading days of the next month inside the grid.

<wa-date-picker style="max-width: 300px;" with-outside-days></wa-date-picker>

Initial View

Use the view attribute to set the initial view. Accepted values are days (default), months, and years.

<wa-date-picker style="max-width: 300px;" view="months"></wa-date-picker>

<wa-date-picker style="max-width: 300px;" view="years"></wa-date-picker>

Conditionally Disabling Dates

For complex rules (e.g. holidays loaded from an API, weekday + odd-week conditions), set the isDateDisabled JavaScript property to a function that receives a Date and returns true to disable it. This runs in addition to the declarative disabled-* attributes — a date is disabled if any rule matches it.

<wa-date-picker style="max-width: 300px;" class="custom-disabled"></wa-date-picker>

<script type="module">
  import { allDefined } from '/dist/webawesome.js';
  await allDefined();

  const picker = document.querySelector('.custom-disabled');
  // Disable every other Monday
  picker.isDateDisabled = date => {
    if (date.getDay() !== 1) return false;
    const week = Math.floor(date.getDate() / 7);
    return week % 2 === 0;
  };
</script>

Custom Day Content

To render custom content inside a specific day cell, provide a slot named day-YYYY-MM-DD. The slotted content replaces the day's label but the button chrome (data attributes, ARIA, click handling) is preserved. This is useful for badges, dots, or holiday labels.

<wa-date-picker style="max-width: 300px;" value="2026-12-25">
  <span slot="day-2026-01-01">🎆</span>
  <span slot="day-2026-02-14">❤️</span>
  <span slot="day-2026-03-17">🍀</span>
  <span slot="day-2026-04-22">🌍</span>
  <span slot="day-2026-10-31">🎃</span>
  <span slot="day-2026-12-25">🎄</span>
</wa-date-picker>

Dynamic Day Content

For content that follows a rule across many dates (e.g. paydays, recurring events, moving holidays), set the dayContent JavaScript property to a function that receives a Date and returns a string of HTML, a Lit TemplateResult, or null to use the default label. This runs for every rendered day cell, so it scales to any year the user navigates to.

If both a day-YYYY-MM-DD slot and dayContent apply to the same date, the slot wins.

<wa-date-picker style="max-width: 300px;" class="dynamic-days"></wa-date-picker>

<script type="module">
  import { allDefined } from '/dist/webawesome.js';
  await allDefined();

  const picker = document.querySelector('.dynamic-days');
  picker.dayContent = date => {
    const day = date.getDate();
    const lastDay = new Date(date.getFullYear(), date.getMonth() + 1, 0).getDate();

    // Mark paydays: the 15th and the last day of each month
    if (day === 15 || day === lastDay) {
      const id = `payday-${date.toISOString().slice(0, 10)}`;
      return `<wa-tooltip for="${id}">Payday</wa-tooltip><span id="${id}">💰</span>`;
    }

    return null;
  };
</script>

Custom Footer

Add buttons or other content below the calendar using the footer slot. The picker exposes goToToday() and clear() methods for common shortcut buttons.

<wa-date-picker style="max-width: 300px;" class="footer-example">
  <div slot="footer">
    <wa-button class="today-btn" size="s" appearance="outlined">Today</wa-button>
    <wa-button class="clear-btn" size="s" appearance="outlined">Clear</wa-button>
  </div>
</wa-date-picker>

<script type="module">
  import { allDefined } from '/dist/webawesome.js';
  await allDefined();

  const picker = document.querySelector('.footer-example');
  picker.querySelector('.today-btn').addEventListener('click', () => {
    picker.value = new Date();
    picker.goToToday();
  });
  picker.querySelector('.clear-btn').addEventListener('click', () => picker.clear());
</script>

Custom Navigation Icons

Replace the default chevrons by slotting your own icons into previous-icon and next-icon.

<wa-date-picker style="max-width: 300px;">
  <wa-icon slot="previous-icon" name="caret-left"></wa-icon>
  <wa-icon slot="next-icon" name="caret-right"></wa-icon>
</wa-date-picker>

Listening for Changes

The change event fires when the user commits a new value. In range mode, input also fires after the first click of a new range, before commit.

<wa-date-picker style="max-width: 600px;" mode="range" months="2" class="change-listener"></wa-date-picker>
<output class="change-output"></output>

<script type="module">
  import { allDefined } from '/dist/webawesome.js';
  await allDefined();

  const picker = document.querySelector('.change-listener');
  const output = document.querySelector('.change-output');

  picker.addEventListener('change', () => {
    output.textContent = `Value: ${picker.value}`;
  });

  picker.addEventListener('wa-focus-day', event => {
    console.log('focused', event.detail.date);
  });
</script>

API

Importing

If you're using the autoloader or a hosted project, components load on demand — no manual import needed. To cherry-pick a component manually, use one of the following snippets.

import 'https://ka-f.webawesome.com/[email protected]/components/date-picker/date-picker.js';

import '@awesome.me/webawesome/dist/components/date-picker/date-picker.js';

import './webawesome/dist/components/date-picker/date-picker.js';

import WaDatePicker from '@awesome.me/webawesome/dist/react/date-picker/index.js';

Slots

Learn more about using slots.

Attributes & Properties

Learn more about attributes and properties.

Methods

Learn more about methods.

Events

Learn more about events.

Custom States

Learn more about custom states.

CSS Parts

Learn more about CSS parts.

Dependencies

This component automatically imports the following elements. Sub-dependencies, if any exist, will also be included in this list.

• <wa-icon>