Timepicker
Use when
Use timepickers when users need to specify the time of day.
Use two timepickers when users need to specify start and stop times.
Don't use when
Don't use timepickers when users need to specify general durations or time spans. Use radio buttons or HTML select fields instead.
12-hour timepicker
Use the 12-hour option for regions and users that use 12-hour time designations. This allows users to select hours, minutes, and "AM" or "PM."
24-hour timepicker
Use the 24-hour option for regions and users that use 24-hour time designations. This allows users to select hours and minutes.
Required field marker
When a timepicker is required, a red asterisk appears to the right of the label. It includes the appropriate ARIA attributes to support users of assistive technologies. For more information about required fields, see the form design guidelines.
Help inline button
When you need to supplement a timepicker label with additional information but don't require persistent inline help, you can place a help inline button beside the label to invoke contextual user assistance.
Hint text
To highlight important considerations about a timepicker, use hint text. This persistent inline help can explain details such as:
- The correct format
- Any constraints on the input
- Additional instructions or context, such as how data is used
Stacked margin
For consistent vertical spacing when a timepicker is immediately followed by another form input, use stacked
Don't use stacked
- Is the last input before a field group
- Is the last input on a form
- Is followed by one or more conditional fields (use
sky-margin-stacked-sm
Keyboard entries
Users can use the keyboard to enter time values in the input field. Times automatically resolve to the correct format when the field loses focus.
Use 1/2- or 1/3-width columns for individual timepicker fields inside modals, except when using small (300px) modals. When using two timepickers for start and stop times, use 10px of horizontal space between them.
Components
Guidelines
- NPM package
@skyux/datetimeView in NPM | View in GitHub None found.- Install with NPM
npm install --save-exact @skyux/datetimeNone found.
To enable standard form features, you must wrap the timepicker in an input box. Use labelTexthelpInlineContenthelpKeyhintTextstackedsky-form-errorsky-input-box
import { SkyTimepickerModule } from '@skyux/datetime';
Selector: sky-timepicker
Creates a SKY UX-themed replacement for the HTML input element with type="time".
The value that users select is driven through the ngModel attribute
specified on the input element. You must wrap this component around an input
with the skyTimepickerInput directive.
Outputs
selectedTimeChanged: EventEmitter<SkyTimepickerTimeOutput>
Fires when the value in the timepicker input changes.
Selector: [skyTimepickerInput]
Inputs
skyTimepickerInput: SkyTimepickerComponent | undefined
Creates the timepicker input field and picker. Place this attribute on an input element,
and wrap the input in a sky-timepicker component.
This attribute must be set to the instance of the sky-timepicker.
disabled: boolean
Whether to disable the timepicker on template-driven forms. Don't use this input on reactive forms because they may overwrite the input or leave the control out of sync.
To set the disabled state on reactive forms, use the FormControl instead.
Default: false
returnFormat: string | undefined
The custom time format. For examples, see the moment.js docs.
timeFormat: SkyTimepickerTimeFormatType
The 12-hour hh or 24-hour HH time format for the input.
Default: "hh"
type SkyTimepickerTimeFormatType = "hh" | "HH"
interface SkyTimepickerTimeOutput {
customFormat: string;
hour: number;
iso8601: Date;
local: string;
meridie: string;
minute: number;
timezone: number;
}Properties
customFormat: string
The time format string.
hour: number
The hour.
iso8601: Date
The date in iso8601 format.
local: string
The date in the current local time format.
meridie: string
The meridian (AM or PM).
minute: number
The minute.
timezone: number
The time zone.
SKY UX test harnesses are built upon Angular CDK component harnesses. For more information see the Angular CDK component harness documentation.
import { SkyTimepickerHarness } from '@skyux/datetime/testing';
Harness for interacting with timepicker components in tests.
Methods
clickSelectorButton(): Promise<void>
Clicks the selector button.
Returns
Promise<void>
getControl(): Promise<SkyTimepickerInputHarness>
Gets the timepicker input harness.
Returns
Promise<SkyTimepickerInputHarness>
getTimepickerSelector(): Promise<SkyTimepickerSelectorHarness>
Gets the SkyTimepickerSelectorHarness for the selector controlled by
the timepicker. Throws an error if the selector is not open.
Returns
Promise<SkyTimepickerSelectorHarness>
isTimepickerOpen(): Promise<boolean>
Whether the timepicker calendar picker is open.
Returns
Promise<boolean>
SkyTimepickerHarness.with(filters: SkyTimepickerFilters): HarnessPredicate<SkyTimepickerHarness>
Gets a HarnessPredicate that can be used to search for a
SkyTimepickerHarness that meets certain criteria.
These filters only work for standalone timepickers. For timepickers
wrapped inside sky-input-box, place filters on the input box instead and
query the timepicker using a SkyInputBoxHarness.
For the input box implementation, see the code example.
Parameters
filters: SkyTimepickerFilters
Returns
HarnessPredicate<SkyTimepickerHarness>
A set of criteria that can be used to filter a list of SkyTimepickerHarness instances.
interface SkyTimepickerFilters {
dataSkyId?: string | RegExp;
}Properties
dataSkyId?: string | RegExp
Only find instances whose data-sky-id attribute matches the given value.
import { SkyTimepickerSelectorHarness } from '@skyux/datetime/testing';
Harness for interacting with a timepicker selector in tests.
Methods
clickHour(value: string): Promise<void>
Clicks the specified hour button, or throws an error if it does not exist.
Parameters
value: string
Returns
Promise<void>
clickMeridie(value: string): Promise<void>
Clicks the specified meridie button, or throws an error if it does not exist.
Parameters
value: string
Returns
Promise<void>
clickMinute(value: string): Promise<void>
Clicks the specified minute button, or throws an error if it does not exist.
Parameters
value: string
Returns
Promise<void>
getSelectedValue(): Promise<undefined | string>
Gets the time value of the currently selected items.
Returns
Promise<undefined | string>
getSelectorMode(): Promise<string>
Gets the current calendar mode.
Returns
Promise<string>
Loading...