Light Dark System

Time Picker

<cw-time-picker> | CwTimePicker
Since 1.1 experimental

Time pickers let users select a time from a set of predefined hour, minute, second, and meridiem columns. 

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

import CwTimePicker from '@cordwainer/cw-elements/dist/react/time-picker';

const App = () => <CwTimePicker label="Select a time" />;

Examples

Labels & Help Text

Use the label attribute to give the time 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-time-picker label="Meeting time" help-text="Choose a time for the daily standup."></cw-time-picker>

import CwTimePicker from '@cordwainer/cw-elements/dist/react/time-picker';

const App = () => <CwTimePicker label="Meeting time" help-text="Choose a time for the daily standup." />;

Placeholders

Use the placeholder attribute to add a placeholder.

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

import CwTimePicker from '@cordwainer/cw-elements/dist/react/time-picker';

const App = () => <CwTimePicker placeholder="Select a time" />;

Setting Initial Values

Use the value attribute to set an initial value. The value is a 24-hour, zero-padded time string (e.g. "14", "14:08", or "14:08:32") whose precision matches granularity. 

<cw-time-picker label="Appointment" value="14:30"></cw-time-picker>

import CwTimePicker from '@cordwainer/cw-elements/dist/react/time-picker';

const App = () => <CwTimePicker label="Appointment" value="14:30" />;

Granularity

Use the granularity attribute to control the smallest unit of time the user can set. Valid options are hour, minute (the default), and second. The picker’s listbox and value format both adjust to match. 



<cw-time-picker label="Hour" granularity="hour" value="14"></cw-time-picker>
<br />
<cw-time-picker label="Minute" granularity="minute" value="14:08"></cw-time-picker>
<br />
<cw-time-picker label="Second" granularity="second" value="14:08:32"></cw-time-picker>

import CwTimePicker from '@cordwainer/cw-elements/dist/react/time-picker';

const App = () => (
  <>
    <CwTimePicker label="Hour" granularity="hour" value="14" />
    <br />
    <CwTimePicker label="Minute" granularity="minute" value="14:08" />
    <br />
    <CwTimePicker label="Second" granularity="second" value="14:08:32" />
  </>
);

Hour Format

By default, the time picker shows a 12- or 24-hour clock based on the page’s locale. Use the hour-format attribute to override this. Valid options are auto (the default), 12, and 24. When 12 is used, an additional AM/PM column is shown. 


<cw-time-picker label="12-hour" hour-format="12" value="14:30"></cw-time-picker>
<br />
<cw-time-picker label="24-hour" hour-format="24" value="14:30"></cw-time-picker>

import CwTimePicker from '@cordwainer/cw-elements/dist/react/time-picker';

const App = () => (
  <>
    <CwTimePicker label="12-hour" hour-format="12" value="14:30" />
    <br />
    <CwTimePicker label="24-hour" hour-format="24" value="14:30" />
  </>
);

Clearable

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

<cw-time-picker label="Clearable" value="09:00" clearable></cw-time-picker>

import CwTimePicker from '@cordwainer/cw-elements/dist/react/time-picker';

const App = () => <CwTimePicker label="Clearable" value="09:00" clearable />;

Disabled

Use the disabled attribute to disable a time picker.

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

import CwTimePicker from '@cordwainer/cw-elements/dist/react/time-picker';

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

Filled & Pill

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


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

<br />

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

import CwTimePicker from '@cordwainer/cw-elements/dist/react/time-picker';

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

    <br />

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

Sizes

Use the size attribute to change a time picker’s size. Note that size does not apply to listbox options. 



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

<br />

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

<br />

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

import CwTimePicker from '@cordwainer/cw-elements/dist/react/time-picker';

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

    <br />

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

    <br />

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

Placement

The preferred placement of the time picker’s listbox 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-time-picker placement="top"></cw-time-picker>

import CwTimePicker from '@cordwainer/cw-elements/dist/react/time-picker';

const App = () => <CwTimePicker 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-time-picker placeholder="Meeting time" clearable>
  <cw-icon name="calendar-event" slot="prefix"></cw-icon>
  <cw-badge slot="suffix">New</cw-badge>
</cw-time-picker>

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

const App = () => (
  <CwTimePicker placeholder="Meeting time" clearable>
    <CwIcon name="calendar-event" slot="prefix"></CwIcon>
    <CwBadge slot="suffix">New</CwBadge>
  </CwTimePicker>
);

Roadmap

The time picker currently supports selecting an hour, minute, second, and meridiem from scrollable columns. The following enhancements are planned for future releases:

  • Analog clock picker mode — an alternate picker="clock" mode that presents an analog clock face for selecting hours, minutes, and seconds.
    • 12 hour positions around a circle (or a dual-ring 24-hour face for hour-format="24") with a hand pointing at the selected value.
    • Selecting an hour automatically advances the face to minutes, and to seconds when granularity="second".
    • Numbers are click- and keyboard-selectable (arrow keys move the selection), with click-and-drag of the hand as a progressive enhancement for pointer and touch input.

[component-metadata:cw-time-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/time-picker/time-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/time-picker/time-picker.js';

To import this component using a bundler:

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

To import this component as a React component:

import CwTimePicker from '@cordwainer/cw-elements/dist/react/time-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 time picker, submitted as a name/value pair with form data. string ''
value The current value of the time picker, submitted as a name/value pair with form data. The value is a 24-hour, zero-padded string whose precision matches granularity (e.g. "14", "14:08", or "14:08:32"). - -
defaultValue
value 		The default value of the form control. Primarily used for resetting the form control. string ''
granularity The smallest unit of time the picker allows the user to set. TimeGranularity 'minute'
hourFormat
hour-format 		The hour format to use. When auto, the format is determined by the page’s locale. When 12, hours are shown from 1–12 alongside an AM/PM column. When 24, hours are shown from 00–23. HourFormat 'auto'
size The time picker’s size. 'small' | 'medium' | 'large' 'medium'
placeholder Placeholder text to show as a hint when the time picker is empty. string ''
disabled Disables the time picker. boolean false
clearable Adds a clear button when the time picker is not empty. boolean false
open Indicates whether or not the time picker is open. You can toggle this attribute to show and hide the listbox, or you can use the show() and hide() methods and this attribute will reflect the time picker’s open state. boolean false
hoist Enable this option to prevent the listbox 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 time picker. boolean false
pill Draws a pill-style time picker with rounded edges. boolean false
label The time picker’s label. If you need to display HTML, use the label slot instead. string ''
placement The preferred placement of the time picker’s listbox. Note that the actual placement may vary as needed to keep the listbox inside of the viewport. 'top' | 'bottom' 'bottom'
helpText
help-text 		The time 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 time 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 time picker’s listbox opens. -
cw-after-show onCwAfterShow Emitted after the time picker’s listbox opens and all animations are complete. -
cw-hide onCwHide Emitted when the time picker’s listbox closes. -
cw-after-hide onCwAfterHide Emitted after the time picker’s listbox 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 listbox. -
hide() Hides the listbox. -
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 time 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 time, an <input> element.
listbox The listbox container where the hour/minute/second/meridiem columns are rendered.
column One of the listbox’s columns.
option An individual option within a column.
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-option>
  • <cw-popup>