UITimePicker

UITimePicker

UITimePicker is a component that allows users to input or select a time value. It provides a dropdown panel with selectable hour, minute, and optionally second inputs, as well as AM/PM selection when in 12-hour format.

<template>
  <UITimePicker
    v-model="selectedTime"
    format="HH:mm"
    placeholder="Select time"
  />
</template>

<script setup>
import { ref } from 'vue';

const selectedTime = ref(null);
</script>

Props

• modelValue (string | Date | null): The selected time value, to be used with v-model
• format (string, default: ‘HH:mm:ss’): Time format string
• placeholder (string, default: ‘Select time’): Input placeholder text
• disabled (boolean, default: false): Whether the component is disabled
• clearable (boolean, default: true): Whether to show a clear button
• size (‘small’ | ‘medium’ | ‘large’, default: ‘medium’): Size of the component
• inputReadOnly (boolean, default: false): Whether the input is read-only
• use12Hours (boolean, default: false): Whether to use 12-hour format with AM/PM
• hourStep (number, default: 1): Interval between hours in the picker
• minuteStep (number, default: 1): Interval between minutes in the picker
• secondStep (number, default: 1): Interval between seconds in the picker
• disabledHours (Function): Function that returns disabled hour options
• disabledMinutes (Function): Function that returns disabled minute options
• disabledSeconds (Function): Function that returns disabled second options
• hideDisabledOptions (boolean, default: false): Whether to hide disabled options
• allowClear (boolean, default: true): Whether to allow clearing the selected time
• open (boolean): Whether the dropdown panel is visible
• placement (‘bottomLeft’ | ‘bottomRight’ | ‘topLeft’ | ‘topRight’, default: ‘bottomLeft’): Placement of the dropdown panel

Events

• update:modelValue (value: string | Date | null): Emitted when the selected time changes
• focus (event: FocusEvent): Emitted when the component gains focus
• blur (event: FocusEvent): Emitted when the component loses focus
• change (value: string | Date | null): Emitted when the user confirms a time selection
• open-change (open: boolean): Emitted when the dropdown panel is opened or closed
• clear (): Emitted when the clear button is clicked

Slots

• prefix: Custom prefix content in the input
• suffix: Custom suffix content in the input
• renderExtraFooter: Additional footer content for the dropdown panel

Usage Examples

1. Basic Usage:

<template>
  <UITimePicker v-model="time" />
</template>

<script setup>
import { ref } from 'vue';

const time = ref('13:30:00');
</script>

2. Custom Format:

<template>
  <UITimePicker
    v-model="time"
    format="h:mm a"
    :use12Hours="true"
  />
</template>

<script setup>
import { ref } from 'vue';

const time = ref('1:30 pm');
</script>

3. Time Steps:

<template>
  <UITimePicker
    v-model="time"
    format="HH:mm"
    :minuteStep="15"
    :hourStep="2"
  />
</template>

<script setup>
import { ref } from 'vue';

const time = ref('14:00');
</script>

4. Disabled Options:

<template>
  <UITimePicker
    v-model="time"
    format="HH:mm"
    :disabledHours="disabledHours"
    :disabledMinutes="disabledMinutes"
  />
</template>

<script setup>
import { ref } from 'vue';

const time = ref('14:30');

const disabledHours = () => {
  return [0, 1, 2, 3, 4, 5, 6, 7, 20, 21, 22, 23];
};

const disabledMinutes = (selectedHour) => {
  if (selectedHour === 8) {
    return Array.from({ length: 30 }, (_, i) => i); // Disable first 30 minutes for 8 AM
  }
  return [];
};
</script>

5. With Date Picker:

<template>
  <div>
    <UIDatePicker
      v-model:value="date"
      valueType="date"
    />
    <UITimePicker
      v-model="time"
      style="margin-left: 8px;"
    />
    <div class="selected-datetime">
      Selected: {{ formatDateTime(date, time) }}
    </div>
  </div>
</template>

<script setup>
import { ref, computed } from 'vue';
import dayjs from 'dayjs';

const date = ref(new Date());
const time = ref('12:00:00');

const formatDateTime = (date, time) => {
  if (!date || !time) return '';

  const [hours, minutes, seconds] = time.split(':');
  const datetime = new Date(date);
  datetime.setHours(parseInt(hours));
  datetime.setMinutes(parseInt(minutes));
  datetime.setSeconds(parseInt(seconds || 0));

  return dayjs(datetime).format('YYYY-MM-DD HH:mm:ss');
};
</script>

Best Practices

1. Time Format:

   • Use appropriate time format for your locale
   • Consider 12-hour vs 24-hour format based on user preference
   • Clearly indicate which format is being used
   • Use consistent time format across your application

2. User Experience:

   • Use clear input placeholders
   • Consider step intervals for specific use cases
   • Use input read-only mode to prevent keyboard errors
   • Provide clear validation messages for invalid times

3. Validation:

   • Validate time inputs appropriately
   • Disable hours/minutes that are not valid selections
   • Consider time range validations when needed
   • Use the combined value appropriately in forms

4. Accessibility:

   • Ensure keyboard navigation works properly
   • Include appropriate ARIA attributes
   • Provide sufficient color contrast
   • Ensure focus states are clearly visible