Time Picker (Native)

TuiTimePickerNative is a component encapsulated based on the browser's native <input type="date/time/...">. It utilizes the operating system's built-in time selection controls, such as scroll wheels on mobile devices or native calendars on desktops, providing a lightweight footprint and excellent mobile experience.

Compatibility Note

This component relies on native browser implementations:

1. UI Differences: Popup styles vary significantly across different browsers (Chrome, Safari, Firefox) and operating systems (Windows, Mac, Android, iOS).
2. Feature Support: type="datetime" is internally converted to datetime-local.
3. Firefox/Safari: Certain types like week or month may not be supported in Firefox or older versions of Safari, falling back to a standard text input.

Basic Usage

Date and Time

The selection type is controlled via the type property.

• date (Default): Select year, month, and day.
• datetime: Select year, month, day, and time (renders internally as type="datetime-local").
• time: Select time only.

<script setup>
import { ref } from 'vue';
const dateVal = ref('');
const timeVal = ref('');
</script>

<template>
  <div class="demo-gap">
    <TuiTimePickerNative v-model="dateVal" type="date" placeholder="Select Date" />
    <TuiTimePickerNative v-model="timeVal" type="time" placeholder="Select Time" />
  </div>
</template>

Dependency: Day.js

To provide flexible formatting capabilities on top of native controls, this component uses the Day.js library for date parsing and formatting.

• Format Standards: The format property fully supports Day.js format placeholders (e.g., YYYY for a four-digit year, MM for a two-digit month).
• Robustness: The component automatically processes standard ISO format strings returned by the native input and converts them into your specified display format.

Formatted Display

While the native input value always follows the ISO standard format (e.g., YYYY-MM-DD), this component supports customizing the text format displayed in the input box via the format property.

Principle

The component internally maintains a text box for display and a hidden native input. When a user selects a native date, the component formats it using dayjs for the user's view, while the v-model binding remains in the standard ISO format.

<template>
  <TuiTimePickerNative 
    type="date" 
    v-model="val1" 
    format="YYYY-MM-DD" 
  />

  <TuiTimePickerNative 
    type="datetime" 
    v-model="val2" 
    format="YYYY/MM/DD HH:mm" 
  />
</template>

Other Types

Support is also provided for selecting months and weeks.

• month: Select year and month.
• week: Select a specific week of a year.

Note: Ensure testing in Webkit-based browsers like Chrome or Edge, as Firefox may not support these types.

<template>
  <TuiTimePickerNative type="month" format="YYYY-MM" />
  <TuiTimePickerNative type="week" format="YYYY-ww" />
</template>

Constraints and Status

Most native input constraint attributes are supported:

• min / max: Restrict the selectable date range.
• step: Set the time step (e.g., step="60" for seconds).
• clearable: Whether to display a clear button.
• disabled / readonly: Disable the component or set it to read-only.

<template>
  <TuiTimePickerNative 
    type="date" 
    min="2023-01-01" 
    max="2023-12-31" 
    clearable 
    placeholder="Valid within 2023" 
  />
</template>

API Reference

Props

Property	Type	Default	Description
modelValue	String/Date	-	Bound value.
type	String	'date'	Type. Options: date, time, datetime (mapped to datetime-local), month, week.
format	String	-	Formatted string for display (based on Day.js specification).
size	String	'default'	Size. Options: large, default, small.
clearable	Boolean	false	Whether it is clearable.
placeholder	String	-	Placeholder text.
min	String	-	Native attribute, minimum allowed value.
max	String	-	Native attribute, maximum allowed value.
step	String/Number	-	Native attribute, step size.
disabled	Boolean	false	Whether it is disabled.
readonly	Boolean	false	Whether it is read-only.
prefixIcon	String	-	Header icon class name.
suffixIcon	String	-	Suffix icon class name.

Events

Event Name	Description	Callback Parameters
update:modelValue	Triggered when the bound value changes.	(value)
change	Triggered on blur if the value has changed.	(value)
focus	Triggered when gaining focus.	(event)
blur	Triggered when losing focus.	(event)
clear	Triggered when the clear button is clicked.	-

Exposed Methods

Method Name	Description
focus	Focuses the input box.
blur	Removes focus from the input box.
openPicker	Core Function. Manually triggers the native date selection popup (simulates a click).