Input · TimePicker

TimePicker

Users can easily select a compliant, formatted point of time using the time selector.

Demos

How to import

<script setup lang="ts">
    import { TimePicker } from '@fibrous/semi-ui-vue';
</script>

Basic Usage

Click TimePicker, and then you can select or enter a time in the floating layer.

Code
<script setup lang="ts">
    import { TimePicker } from '@fibrous/semi-ui-vue';
</script>

<template>
    <TimePicker />
</template>

Infinite Scroll

Starting from version V2.22.0, we changed the default mode of ScrollItem in TimePicker from wheel to normal. If you want to apply the effect of infinite scrolling back, please refer to the following example.

Code
<script setup lang="ts">
    import { TimePicker } from '@fibrous/semi-ui-vue';
</script>

<template>
    <TimePicker :scrollItemProps="{ mode: 'wheel', cycled: true }" />
</template>

Controlled Component

Use v-model as a controlled component, and defaultValue for the initial value. null is a controlled empty value and undefined means uncontrolled; when a controlled value goes back to undefined the input is cleared and the picker becomes uncontrolled. After clearing, v-model receives undefined (single) or an empty array (range).

Code
<script setup lang="ts">
    import { ref } from 'vue';
    import { TimePicker } from '@fibrous/semi-ui-vue';

    const value = ref<Date | (Date | undefined)[] | null | undefined>(null);
    const onChange = (time: unknown) => console.log(time);
</script>

<template>
    <TimePicker v-model="value" @change="onChange" />
</template>

Different Format

The columns in the TimePicker float will follow format Change, when omitted format At some point, the corresponding column in the floating layer will also disappear.

NOTE: format Follow the date-fns v4 format Format. https://date-fns.org/docs/format

Code
<script setup lang="ts">
    import { TimePicker } from '@fibrous/semi-ui-vue';
</script>

<template>
    <TimePicker defaultValue="10:24" format="HH:mm" />
</template>

Disable Time Selection

Code
<script setup lang="ts">
    import { TimePicker } from '@fibrous/semi-ui-vue';
</script>

<template>
    <TimePicker defaultValue="12:08:23" disabled />
</template>

Set Step Length

Available Hour Step, Minute Step, Second Step Show the optional minutes and seconds by step.

Code
<script setup lang="ts">
    import { TimePicker } from '@fibrous/semi-ui-vue';
</script>

<template>
    <TimePicker :minuteStep="15" :secondStep="10" />
</template>

12-hour System

12-hour time selector, default format for a h:mm:ss, an incoming format The format must be in dateFns date formatWithin range.

For example, the default 12-hour format string is:a h:mm:ss, if passed in A h:mm:ss This will result in an inability to format correctly.



Code
<script setup lang="ts">
    import { TimePicker } from '@fibrous/semi-ui-vue';
</script>

<template>
    <div>
        <TimePicker use12Hours />
        <br />
        <br />
        <TimePicker format="a h:mm" use12Hours />
    </div>
</template>

Time Range

Pass type = "timeRange" to enable time range selection.



Code
<script setup lang="ts">
    import { TimePicker } from '@fibrous/semi-ui-vue';
</script>

<template>
    <div>
        <TimePicker :defaultValue="['10:23:15', '12:38:32']" type="timeRange" />
        <br />
        <br />
        <TimePicker :defaultValue="['上午 08:11', '下午 11:21']" format="a h:mm" type="timeRange" use12Hours />
    </div>
</template>

Disable left/right panels in Range mode (disabledTime)

When type="timeRange", you can use disabledTime(value, panelType) to apply different disabled rules for the left/right panel.

  • value: the currently selected times, the unpicked side undefined (e.g. [date, undefined]); an empty array when there is no value, and length 1 when value, defaultValue or the input holds a single time
  • panelType: 'left' | 'right', representing start/end panel

In the following demo, after selecting a start time, the right (end) panel will disable options earlier than the start time.

Code
<script setup lang="ts">
    import { TimePicker } from '@fibrous/semi-ui-vue';

    const range = (length: number) => Array.from({ length }, (_, i) => i);

    // The right panel disables everything earlier than the start time picked on the left
    const disabledTime = (value: (Date | undefined)[], panelType: 'left' | 'right') => {
        const start = value[0];
        if (panelType === 'right' && start) {
            const h = start.getHours();
            const m = start.getMinutes();
            return {
                disabledHours: () => range(h),
                disabledMinutes: (hour: number) => (hour === h ? range(m) : []),
            };
        }
        return {};
    };
</script>

<template>
    <TimePicker :disabledTime="disabledTime" type="timeRange" />
</template>

Custom Trigger

By default we use the Input component as the trigger for the TimePicker component. You can customize this trigger with the #trigger scoped slot, whose parameters are { value, inputValue, placeholder, disabled, componentProps, onChange }. The unpicked side of value is undefined, and onChange updates the input text as typing would.

Code
<script setup lang="ts">
    import { ref } from 'vue';
    import * as dateFns from 'date-fns';
    import { IconTimePicker } from '@fibrous/semi-icons-vue/lab';
    import { Tag, TimePicker } from '@fibrous/semi-ui-vue';

    const formatToken = 'HH:mm:ss';
    const time = ref<Date | (Date | undefined)[] | undefined>(new Date(2024, 0, 1, 10, 30, 0));
</script>

<template>
    <TimePicker v-model="time" :format="formatToken">
        <template #trigger="{ placeholder }">
            <Tag color="cyan" shape="circle" size="large" :style="{ padding: '12px', paddingRight: '16px', fontSize: '14px' }" type="light">
                <template #prefixIcon>
                    <IconTimePicker />
                </template>
                {{ time instanceof Date ? dateFns.format(time, formatToken) : placeholder }}
            </Tag>
        </template>
    </TimePicker>
</template>

TimeZone Config

Semi All configuration about time zone is converged in ConfigProvider

Select Time Zone:


TimePicker:
Code
<script setup lang="ts">
    import { ref } from 'vue';
    import { ConfigProvider, Select, TimePicker } from '@fibrous/semi-ui-vue';

    const timeZone = ref('GMT+08:00');
    const defaultTimestamp = 1581599305265;
    const gmtList: string[] = [];
    for (let hourOffset = -11; hourOffset <= 14; hourOffset++) {
        const prefix = hourOffset >= 0 ? '+' : '-';
        gmtList.push(`GMT${prefix}${String(Math.abs(hourOffset)).padStart(2, '0')}:00`);
    }

    const onChange = (date: unknown, dateString: string | string[]) => console.log('DatePicker changed: ', date, dateString);
</script>

<template>
    <ConfigProvider :timeZone="timeZone">
        <div :style="{ width: '300px' }">
            <h5 :style="{ margin: '10px' }">Select Time Zone:</h5>
            <Select aria-label="时区" :modelValue="timeZone" placeholder="请选择时区" showClear :style="{ width: '300px' }" @select="timeZone = String($event)">
                <Select.Option v-for="gmt in gmtList" :key="gmt" :value="gmt">{{ gmt }}</Select.Option>
            </Select>
            <br />
            <br />
            <h5 :style="{ margin: '10px' }">TimePicker:</h5>
            <TimePicker :defaultValue="defaultTimestamp" @change="onChange" />
        </div>
    </ConfigProvider>
</template>

API Reference

Props

PropertyDescriptionTypeDefault
modelValueCurrent time, used with v-model; an array when type is timeRange. null is a controlled empty value, and undefined means uncontrolled.TimePickerValue | (TimePickerValue | undefined)[] | nullundefined
defaultValueInitial time when uncontrolled, in the same forms as modelValue.TimePickerValue | (TimePickerValue | undefined)[]semiGlobalDefault("TimePicker", "defaultValue")
openWhether the panel is open, used with v-model:open; undefined means uncontrolled.booleanundefined
defaultOpenWhether the panel is open by default when uncontrolled.booleansemiDefault("TimePicker", "defaultOpen", false)
typeSelection type: time for a single time, timeRange for a range.TimePickerTypesemiDefault("TimePicker", "type", strings.DEFAULT_TYPE)
formatDisplay format, following date-fns format. Defaults to a h:mm:ss with use12Hours, else HH:mm:ss.stringsemiGlobalDefault("TimePicker", "format")
use12HoursUses the 12-hour clock.booleansemiDefault("TimePicker", "use12Hours", false)
hourStepInterval of the hour options; a positive integer.numbersemiGlobalDefault("TimePicker", "hourStep")
minuteStepInterval of the minute options; a positive integer.numbersemiGlobalDefault("TimePicker", "minuteStep")
secondStepInterval of the second options; a positive integer.numbersemiGlobalDefault("TimePicker", "secondStep")
disabledDisables all interaction.booleansemiDefault("TimePicker", "disabled", false)
disabledHoursReturns the hours that cannot be selected.Type(() => number[])undefined
disabledMinutesReturns the minutes that cannot be selected for the selected hour.Type((selectedHour: number) => number[])undefined
disabledSecondsReturns the seconds that cannot be selected for the selected hour and minute.Type((selectedHour: number, selectedMinute: number) => number[])undefined
disabledTimeRange mode only: returns the disabled rules of the left and right panel from the current value and the panel. The unpicked side of value is undefined; a returned disabledHours, disabledMinutes or disabledSeconds overrides the prop of the same name, and one left out falls back to it.Type((value: (Date | undefined)[], panelType: PanelType) => DisabledTimeFns)undefined
hideDisabledOptionsHides the options that cannot be selected.booleansemiDefault("TimePicker", "hideDisabledOptions", false)
placeholderHint shown without a value; defaults to the locale text of type.stringsemiGlobalDefault("TimePicker", "placeholder")
rangeSeparatorSeparator between the two times of a range.stringTypesemiDefault("TimePicker", "rangeSeparator", strings.DEFAULT_RANGE_SEPARATOR)
sizeSize of the input.SizesemiDefault("TimePicker", "size", "default")
borderlessBorderless mode.booleansemiDefault("TimePicker", "borderless", false)
showClearWhether to show the clear button.booleansemiDefault("TimePicker", "showClear", true)
inputReadOnlyMakes the input read-only, which avoids opening the virtual keyboard on mobile devices.booleansemiDefault("TimePicker", "inputReadOnly", false)
validateStatusValidation status."default" | "error" | "warning" | "success"semiGlobalDefault("TimePicker", "validateStatus")
insetLabelIdid of the insetLabel, referenced through aria-labelledby.stringundefined
inputStyleStyle of the input's root element.StyleValuesemiGlobalDefault("TimePicker", "inputStyle")
autofocusFocuses the input on mount, which opens the panel.booleansemiDefault("TimePicker", "autofocus", false)
focusOnOpenFocuses the input and selects its content once mounted, which opens the panel.booleansemiDefault("TimePicker", "focusOnOpen", false)
preventScrollWhether the browser should scroll the document to show the newly focused element; applies to the focus call inside the component.booleansemiGlobalDefault("TimePicker", "preventScroll")
motionWhether the popup animates.booleansemiDefault("TimePicker", "motion", true)
autoAdjustOverflowWhether to flip the popup automatically when it is clipped.booleansemiDefault("TimePicker", "autoAdjustOverflow", true)
positionPopup position. Defaults to bottom when type is timeRange, and bottomLeft when it is time.Type"top" | "bottom" | "left" | "right" | "topLeft" | "topRight" | "leftTop" | "leftBottom" | "rightTop" | "rightBottom" | "bottomLeft" | "bottomRight" | "leftTopOver" | "rightTopOver" | "leftBottomOver" | "rightBottomOver"semiGlobalDefault("TimePicker", "position")
popupClassNameClass name of the popup.stringsemiGlobalDefault("TimePicker", "popupClassName")
popupStyleStyle of the popup.StyleValuesemiGlobalDefault("TimePicker", "popupStyle")
stopPropagationWhether to stop click events on the popup from bubbling.booleansemiDefault("TimePicker", "stopPropagation", true)
timeZoneTime zone; falls back to the timeZone of ConfigProvider, then to the global default.string | numberundefined
scrollItemPropsProps passed to the columns; only cycled, mode, motion and transform, as on the ScrollItem of ScrollList.TimePickerScrollItemPropssemiGlobalDefault("TimePicker", "scrollItemProps")

Events

EventDescriptionCallback parameters
update:modelValueEmitted when the time changes, for v-model to write back. Cleared, it is undefined (single) or an empty array (range); the unpicked side of a range is undefined.[value: Date | (Date | undefined)[] | undefined]
changeEmitted when the time changes, with (Date value, formatted string); both are arrays in range mode.Type[value: Date | (Date | undefined)[] | undefined, str: string | string[]]
update:openEmitted when the panel opens or closes, for v-model:open to write back.[open: boolean]
openChangeEmitted when the panel opens or closes.[open: boolean]
focusEmitted when the input's root element gains focus; moving focus between the input and the clear button does not emit it.[event: FocusEvent]
blurEmitted when a click outside closes the panel, with the native event of that mousedown; leaving the input does not emit it.[event: MouseEvent]

Slots

SlotDescriptionScope parameters
triggerCustom trigger that replaces the default input; a click anywhere in it opens the panel. Receives value (the unpicked side undefined), inputValue, placeholder, disabled, componentProps and onChange (updates the input text, as typing would).TimePickerTriggerSlotProps
panelHeaderContent above the panel; index is the panel's position (0 for time, 0 or 1 for timeRange). Without it, a range shows the locale's start and end text.TimePickerPanelSlotProps
panelFooterContent below the panel; index is the panel's position.TimePickerPanelSlotProps
panelRange mode only: used as both the header and the footer of panel index, taking precedence over panelHeader and panelFooter while it has content.TimePickerPanelSlotProps
prefixPrefix content of the input.any
insetLabelInset label of the input.any
clearIconCustom clear icon; effective when showClear is true.any

Exposes

NameDescriptionType
focusFocuses the input, which opens the panel; does nothing with a custom trigger.Type() => void
blurRemoves focus from the input; does nothing with a custom trigger.Type() => void

Among undeclared attributes, class and style land on the root element, and the rest (id, title, aria-*, data-*, event listeners and so on) land on the inner input; with a custom #trigger all of them land on the root element, whose role is group when aria-label or aria-labelledby is passed. focus and blur are declared component events, so @focus and @blur receive only the component events, not the native events bubbling up.

focus() and blur() are available through a ref and do nothing with a custom trigger.

Accessibility

ARIA

  • The input has the role combobox with aria-haspopup="dialog", an aria-expanded that follows the panel, and aria-controls pointing at the panel
  • The hour, minute, second and AM/PM columns are listbox lists named "Hour", "Minute", "Second" and "AM/PM"

Keyboard and Focus

  • Focusing the input opens the panel; once it is open, Down Arrow moves focus into the first column
  • Each column is one Tab stop: Up Arrow, Down Arrow, Home, End and typed characters select its value
  • Esc closes the panel; focus inside the panel returns to the input

Content Guidelines

  • The time selector includes at least hours and minutes, such as: 11:30, which can be adapted to 12-hour or 24-hour format during localization
  • When 12-hour clock is selected, it needs to be used together with AM/PM

Design Tokens

These are the component's internal Sass variables and cannot be overridden. To customize styles, override the --semi-* CSS variables (see the Design Token page) or write unlayered CSS rules.
Sass variableValueUsage
$color-timePicker_range_picker_panel_split-bordervar(--semi-color-border)时间选择器菜单分割线颜色
$color-timePicker_range_panel-borderrgba(0, 0, 0, 0.1)时间选择器描边颜色
$width-timePicker_range_panel-border1px时间选择器菜单分割线宽度
$height-timePicker_panel_body252px时间选择器菜单高度
$width-timePicker_panel_list_ampm72px时间选择器菜单中列宽度 - 上午下午
$width-timePicker_panel_list_hour64px时间选择器菜单中列宽度 - 小时
$width-timePicker_panel_list_minute64px时间选择器菜单中列宽度 - 分钟
$width-timePicker_panel_list_second64px时间选择器菜单中列宽度 - 秒
$width-timePicker_range_panel_scrolllist_body-border2px时间范围选择器双排菜单中间分割线宽度
$spacing-timePicker_range_panel_scrolllist_header_body-padding0时间范围选择器菜单header与内容内边距
$radius-timePicker_range_panelvar(--semi-border-radius-medium)时间范围选择器菜单圆角
$radius-timePicker_inputvar(--semi-border-radius-small)时间范围选择器圆角
$shadow-timePicker_range_panelvar(--semi-shadow-elevated)时间范围选择器菜单阴影