Light Dark System

Date Picker

<cw-date-picker> | CwDatePicker
Since 1.1 experimental

Date pickers let users select a date from a calendar.

<cw-date-picker label="Select a date"></cw-date-picker>

import CwDatePicker from '@cordwainer/cw-elements/dist/react/date-picker';

const App = () => <CwDatePicker label="Select a date" />;

Examples

Labels & Help Text

Use the label attribute to give the date picker an accessible label and help-text to add descriptive text. For content that contains HTML, use the label and help-text slots instead. 

<cw-date-picker label="Trip start date" help-text="Choose the first day of your trip."></cw-date-picker>

import CwDatePicker from '@cordwainer/cw-elements/dist/react/date-picker';

const App = () => <CwDatePicker label="Trip start date" help-text="Choose the first day of your trip." />;

Placeholders

Use the placeholder attribute to add a placeholder.

<cw-date-picker placeholder="Select a date"></cw-date-picker>

import CwDatePicker from '@cordwainer/cw-elements/dist/react/date-picker';

const App = () => <CwDatePicker placeholder="Select a date" />;

Setting Initial Values

Use the value attribute to set an initial value. The value is an ISO 8601 date string in YYYY-MM-DD format. 

<cw-date-picker label="Appointment" value="2026-06-15"></cw-date-picker>

import CwDatePicker from '@cordwainer/cw-elements/dist/react/date-picker';

const App = () => <CwDatePicker label="Appointment" value="2026-06-15" />;

Minimum and Maximum Dates

Use the min and max attributes to constrain the range of selectable dates. Dates outside of this range are shown as disabled in the calendar and are enforced by client-side validation. 

<cw-date-picker label="Delivery date" min="2026-06-01" max="2026-06-30"></cw-date-picker>

import CwDatePicker from '@cordwainer/cw-elements/dist/react/date-picker';

const App = () => <CwDatePicker label="Delivery date" min="2026-06-01" max="2026-06-30" />;

First Day of Week

By default, the calendar’s first day of the week is determined by the page’s locale, falling back to Sunday. Use the first-day-of-week attribute to override this. The value is a number from 0 (Sunday) to 6 (Saturday). 

<cw-date-picker label="Week starts on Monday" first-day-of-week="1"></cw-date-picker>

import CwDatePicker from '@cordwainer/cw-elements/dist/react/date-picker';

const App = () => <CwDatePicker label="Week starts on Monday" first-day-of-week="1" />;

Clearable

Use the clearable attribute to make the control clearable. The clear button only appears when the date picker has a value. 

<cw-date-picker label="Clearable" value="2026-06-15" clearable></cw-date-picker>

import CwDatePicker from '@cordwainer/cw-elements/dist/react/date-picker';

const App = () => <CwDatePicker label="Clearable" value="2026-06-15" clearable />;

Disabled

Use the disabled attribute to disable a date picker.

<cw-date-picker label="Disabled" placeholder="Disabled" disabled></cw-date-picker>

import CwDatePicker from '@cordwainer/cw-elements/dist/react/date-picker';

const App = () => <CwDatePicker label="Disabled" placeholder="Disabled" disabled />;

Filled & Pill

Add the filled attribute to draw a filled date picker, or pill to give it rounded edges. 


<cw-date-picker placeholder="Filled" filled></cw-date-picker>

<br />

<cw-date-picker placeholder="Pill" pill></cw-date-picker>

import CwDatePicker from '@cordwainer/cw-elements/dist/react/date-picker';

const App = () => (
  <>
    <CwDatePicker placeholder="Filled" filled />

    <br />

    <CwDatePicker placeholder="Pill" pill />
  </>
);

Sizes

Use the size attribute to change a date picker’s size.



<cw-date-picker placeholder="Small" size="small"></cw-date-picker>

<br />

<cw-date-picker placeholder="Medium" size="medium"></cw-date-picker>

<br />

<cw-date-picker placeholder="Large" size="large"></cw-date-picker>

import CwDatePicker from '@cordwainer/cw-elements/dist/react/date-picker';

const App = () => (
  <>
    <CwDatePicker placeholder="Small" size="small" />

    <br />

    <CwDatePicker placeholder="Medium" size="medium" />

    <br />

    <CwDatePicker placeholder="Large" size="large" />
  </>
);

Placement

The preferred placement of the date picker’s calendar can be set with the placement attribute. Note that the actual position may vary to ensure the panel remains in the viewport. Valid placements are top and bottom. 

<cw-date-picker placement="top"></cw-date-picker>

import CwDatePicker from '@cordwainer/cw-elements/dist/react/date-picker';

const App = () => <CwDatePicker placement="top" />;

Prefix & Suffix

Use the prefix and suffix slots to add presentational icons and text. Avoid slotting in interactive elements, such as buttons, links, etc.

New 
<cw-date-picker placeholder="Trip date" clearable>
  <cw-icon name="airplane" slot="prefix"></cw-icon>
  <cw-badge slot="suffix">New</cw-badge>
</cw-date-picker>

import CwBadge from '@cordwainer/cw-elements/dist/react/badge';
import CwDatePicker from '@cordwainer/cw-elements/dist/react/date-picker';
import CwIcon from '@cordwainer/cw-elements/dist/react/icon';

const App = () => (
  <CwDatePicker placeholder="Trip date" clearable>
    <CwIcon name="airplane" slot="prefix"></CwIcon>
    <CwBadge slot="suffix">New</CwBadge>
  </CwDatePicker>
);

Roadmap

The date picker currently supports selecting a single date with prev/next month navigation. The following enhancements are planned for future releases:

  • Date range selection — allow selecting a start and end date for use cases like booking a stay or filtering by a date range.
  • Faster month/year navigation — a clickable heading that opens month-grid and year-grid views, making it easier to jump to dates far from today (e.g. entering a birthdate).
  • Per-date disabling — a callback-based API for disabling arbitrary individual dates.
  • Pattern-based disabling — disabling dates that match a recurring pattern, such as weekends or holidays.
  • “Today” quick-jump button — a button in the calendar footer that jumps to and focuses today’s date.

[component-metadata:cw-date-picker]

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

Script Import Bundler React

To import this component from the CDN using a script tag: 

<script type="module" src="https://cdn.jsdelivr.net/npm/@cordwainer/cw-elements@1.1.1/cdn/components/date-picker/date-picker.js"></script>

To import this component from the CDN using a JavaScript import: 

import 'https://cdn.jsdelivr.net/npm/@cordwainer/cw-elements@1.1.1/cdn/components/date-picker/date-picker.js';

To import this component using a bundler:

import '@cordwainer/cw-elements/dist/components/date-picker/date-picker.js';

To import this component as a React component:

import CwDatePicker from '@cordwainer/cw-elements/dist/react/date-picker';

Slots

Name Description
label The input’s label. Alternatively, you can use the label attribute.
prefix Used to prepend a presentational icon or similar element to the combobox.
suffix Used to append a presentational icon or similar element to the combobox.
clear-icon An icon to use in lieu of the default clear icon.
expand-icon The icon to show when the control is expanded and collapsed.
help-text Text that describes how to use the input. Alternatively, you can use the help-text attribute.

Learn more about using slots.

Properties

Name Description Reflects Type Default
name The name of the date picker, submitted as a name/value pair with form data. string ''
value The current value of the date picker, submitted as a name/value pair with form data. The value is an ISO 8601 date string in YYYY-MM-DD format. - -
defaultValue
value 		The default value of the form control. Primarily used for resetting the form control. string ''
min The earliest date a user may select, as a YYYY-MM-DD string. string ''
max The latest date a user may select, as a YYYY-MM-DD string. string ''
firstDayOfWeek
first-day-of-week 		The first day of the week, where 0 is Sunday and 6 is Saturday. When not set, the first day of the week is determined by the page’s locale, falling back to Sunday. number | undefined -
size The date picker’s size. 'small' | 'medium' | 'large' 'medium'
placeholder Placeholder text to show as a hint when the date picker is empty. string ''
disabled Disables the date picker. boolean false
clearable Adds a clear button when the date picker is not empty. boolean false
open Indicates whether or not the date picker is open. You can toggle this attribute to show and hide the calendar, or you can use the show() and hide() methods and this attribute will reflect the date picker’s open state. boolean false
hoist Enable this option to prevent the calendar from being clipped when the component is placed inside a container with overflow: auto|scroll. Hoisting uses a fixed positioning strategy that works in many, but not all, scenarios. boolean false
filled Draws a filled date picker. boolean false
pill Draws a pill-style date picker with rounded edges. boolean false
label The date picker’s label. If you need to display HTML, use the label slot instead. string ''
placement The preferred placement of the date picker’s calendar. Note that the actual placement may vary as needed to keep the calendar inside of the viewport. 'top' | 'bottom' 'bottom'
helpText
help-text 		The date picker’s help text. If you need to display HTML, use the help-text slot instead. string ''
form By default, form controls are associated with the nearest containing <form> element. This attribute allows you to place the form control outside of a form and associate it with the form that has this id. The form must be in the same document or shadow root for this to work. string ''
required The date picker’s required attribute. boolean false
validity Gets the validity state object - -
validationMessage Gets the validation message - -
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Events

Name React Event Description Event Detail
cw-change onCwChange Emitted when the control’s value changes. -
cw-clear onCwClear Emitted when the control’s value is cleared. -
cw-input onCwInput Emitted when the control receives input. -
cw-focus onCwFocus Emitted when the control gains focus. -
cw-blur onCwBlur Emitted when the control loses focus. -
cw-show onCwShow Emitted when the date picker’s calendar opens. -
cw-after-show onCwAfterShow Emitted after the date picker’s calendar opens and all animations are complete. -
cw-hide onCwHide Emitted when the date picker’s calendar closes. -
cw-after-hide onCwAfterHide Emitted after the date picker’s calendar closes and all animations are complete. -
cw-invalid onCwInvalid Emitted when the form control has been checked for validity and its constraints aren’t satisfied. -

Learn more about events.

Methods

Name Description Arguments
show() Shows the calendar. -
hide() Hides the calendar. -
checkValidity() Checks for validity but does not show a validation message. Returns true when valid and false when invalid. -
getForm() Gets the associated form, if one exists. -
reportValidity() Checks for validity and shows the browser’s validation message if the control is invalid. -
setCustomValidity() Sets a custom validation message. Pass an empty string to restore validity. message: string
focus() Sets focus on the control. options: FocusOptions
blur() Removes focus from the control. -

Learn more about methods.

Parts

Name Description
form-control The form control that wraps the label, input, and help text.
form-control-label The label’s wrapper.
form-control-input The date picker’s wrapper.
form-control-help-text The help text’s wrapper.
combobox The container the wraps the prefix, suffix, display input, clear icon, and expand icon.
prefix The container that wraps the prefix slot.
suffix The container that wraps the suffix slot.
display-input The element that displays the selected date, an <input> element.
calendar The calendar container where the header and date grid are rendered.
header The calendar’s header containing the previous/next buttons and heading.
heading The heading that displays the focused month and year.
previous-button The button that navigates to the previous month.
next-button The button that navigates to the next month.
grid The grid that contains the weekday headers and days.
day An individual day within the grid.
clear-button The clear button.
expand-icon The container that wraps the expand icon.

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

  • <cw-icon>
  • <cw-icon-button>
  • <cw-popup>