Form Timepicker

<b-form-timepicker> is a BootstrapVue custom time picker input form control, which provides full WAI-ARIA compliance and internationalization support.

Available in BootstrapVue since v2.6.0

Overview

As a form control wrapper component for the <b-time> component, it provides additional validation state presentation and a compact interface. Native HTML5 time inputs vary in presentation, accessibility, and in some instances are not supported by all browsers. <b-form-timepicker> provides a consistent and accessible interface across all browser platforms and devices.

<template>
  <div>
    <b-form-timepicker v-model="value" locale="en"></b-form-timepicker>
    <div class="mt-2">Value: '{{ value }}'</div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        value: ''
      }
    }
  }
</script>

<!-- b-form-timepicker.vue -->

v-model return value

<b-form-timepicker> always returns a string in the format of 'HH:mm:ss' which is the same format returned by native browser <input type="time"> controls. The value will be in the range of '00:00:00' up to '23:59:59' (24-hour clock using the 'h23' hour cycle syntax).

If no time is selected, then <b-form-timepicker> returns an empty string ('').

Disabled and readonly states

Setting the disabled prop will remove all interactivity of the <b-form-timepicker> component.

Setting the readonly prop will disable selecting a time, but will keep the component interactive, allowing for tabbing between spinbuttons. The v-model will not be updated in the readonly state.

<template>
  <div>
    <b-form-group
      label="Select time picker interactive state"
      v-slot="{ ariaDescribedby }"
    >
      <b-form-radio-group
        v-model="state"
        :aria-describedby="ariaDescribedby"
        aria-controls="ex-disabled-readonly"
      >
        <b-form-radio value="disabled">Disabled</b-form-radio>
        <b-form-radio value="readonly">Readonly</b-form-radio>
        <b-form-radio value="normal">Normal</b-form-radio>
      </b-form-radio-group>
    </b-form-group>

    <b-form-timepicker
      id="ex-disabled-readonly"
      :disabled="disabled"
      :readonly="readonly"
    ></b-form-timepicker>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        state: 'disabled'
      }
    },
    computed: {
      disabled() {
        return this.state === 'disabled'
      },
      readonly() {
        return this.state === 'readonly'
      }
    }
  }
</script>

<!-- b-form-timepicker-disabled-readonly.vue -->

Validation states

<b-form-timepicker> supports invalid and valid styling via the boolean state prop. Setting state to boolean false will style the input as invalid, while setting it to boolean true will style it as valid. Setting state to null will not show any validation state styling (the default).

<template>
  <div>
    <label for="timepicker-invalid">Choose a time (invalid style)</label>
    <b-form-timepicker id="datepicker-invalid" :state="false" class="mb-2"></b-form-timepicker>

    <label for="timepicker-valid">Choose a time (valid style)</label>
    <b-form-timepicker id="datepicker-valid" :state="true"></b-form-timepicker>
  </div>
</template>

<!-- b-form-timepicker-validation.vue -->

Note that native browser validation is not available with <b-form-timepicker>.

Styling

Enabling of seconds spinbutton

By default, the seconds spinbutton is not shown. To enable the section of seconds, set the show-seconds prop to true to enable the seconds selection spinbutton. When show-seconds is false (or not provided), the returned value will always have the seconds portion of the time string set to 00.

<template>
  <div>
    <b-form-timepicker v-model="value" show-seconds locale="en"></b-form-timepicker>
    <div class="mt-2">Value: '{{ value }}'</div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        value: ''
      }
    }
  }
</script>

<!-- b-form-timepicker-show-seconds.vue -->

Control sizing

Fancy a smaller or larger <b-form-timepicker> control? Set the size prop to 'sm' for a smaller form control, or 'lg' for a larger form form control. Note this does not affect the size of the popup time selection dialog.

<template>
  <div>
    <label for="timepicker-sm">Small time picker</label>
    <b-form-timepicker id="timepicker-sm" size="sm" locale="en" class="mb-2"></b-form-timepicker>

    <label for="timepicker-lg">Large time picker</label>
    <b-form-timepicker id="timepicker-lg" size="lg" locale="en"></b-form-timepicker>
  </div>
</template>

<!-- b-form-timepicker-control-size.vue -->

Placeholder

Add custom placeholder text to the control, when no date is selected, via the placeholder prop. If a placeholder is not provided, the value of the label-no-time-selected prop is used.

<template>
  <div>
    <label for="timepicker-placeholder">Time picker with placeholder</label>
    <b-form-timepicker id="timepicker-placeholder" placeholder="Choose a time" locale="en"></b-form-timepicker>
  </div>
</template>

<!-- b-form-timepicker-placeholder.vue -->

Optional controls

Add optional control buttons to the bottom of the calendar popup via the props now-button or reset-button. The default close button can be removed via the no-close-button prop.

  • The now button selects the current time
  • The reset button either clears the selected time, or sets the time to the value of the prop reset-value (if provided)
  • The close button closes the time popup
<template>
  <div>
    <label for="timepicker-buttons">Time picker with optional footer buttons</label>
    <b-form-timepicker
      id="timepicker-buttons"
      now-button
      reset-button
      locale="en"
    ></b-form-timepicker>
  </div>
</template>

<!-- b-form-timepicker-footer-buttons.vue -->

The text for the optional buttons can be set via the label-now-button, label-reset-button, and the label-close-button props. Due to the limited width of the footer section, it is recommended to keep these labels short.

Use the dropdown props right, dropup, dropright, dropleft, no-flip, and offset to control the positioning of the popup calendar.

Refer to the <b-dropdown> positioning section for details on the effects and usage of these props.

Button only mode

v2.7.0+

Fancy just a button that launches the timepicker dialog, or want to provide your own optional text input field? Use the button-only prop to render the timepicker as a dropdown button. The formatted time label will be rendered with the class sr-only (available only to screen readers).

In the following simple example, we are placing the timepicker (button only mode) as an append to a <b-input-group>:

<template>
  <div>
    <label for="example-input">Choose a time</label>
    <b-input-group class="mb-3">
      <b-form-input
        id="example-input"
        v-model="value"
        type="text"
        placeholder="HH:mm:ss"
      ></b-form-input>
      <b-input-group-append>
        <b-form-timepicker
          v-model="value"
          button-only
          right
          show-seconds
          locale="en"
          aria-controls="example-input"
        ></b-form-timepicker>
      </b-input-group-append>
    </b-input-group>
    <p>Value: '{{ value }}'</p>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        value: ''
      }
    }
  }
</script>

<!-- b-form-timepicker-button-only.vue -->

Control the size of the button via the size prop, and the button variant via the button-variant prop.

Internationalization

Internationalization of the time interface is provided via Intl.DateTimeFormat and Intl.NumberFormat, except for the labels applied to elements of the time control (aria-labels, selected status, etc.). You must provide your own translations for these labels. The available locales will be browser dependent (not all browsers support all locales).

By default <b-form-timepicker> will use the browser's default locale, but you can specify the locale (or locales) to use via the locale prop. The prop accepts either a single locale string, or an array of locale strings (listed in order of most preferred locale to least preferred).

The emitted 'context' event will include which locale the time control has resolved to (which may not be the same locale as requested, depending on the supported locales of Intl).

For server side rendering (SSR) when using Node.js, ensure that the Node.js runtime you are using supports Intl and the locales you will be using. Refer to the Node Intl support documentation for details.

<template>
  <b-row>
    <b-col cols="12" class="mb-3">
      <label for="example-locales">Locale:</label>
      <b-form-select id="example-locales" v-model="locale" :options="locales"></b-form-select>
    </b-col>
    <b-col md="6">
      <b-form-timepicker
        v-model="value"
        v-bind="labels[locale] || {}"
        :locale="locale"
        show-seconds
        @context="onContext"
      ></b-form-timepicker>
    </b-col>
    <b-col>
      <p>Value: <b>'{{ value }}'</b></p>
      <p class="mb-0">Context:</p>
      <pre class="small">{{ context }}</pre>
   </b-col>
  </b-row>
</template>

<script>
  export default {
    data() {
      return {
        value: '',
        context: null,
        locale: 'en-US',
        locales: [
          { value: 'en-US', text: 'English US (en-US)' },
          { value: 'de', text: 'German (de)' },
          { value: 'ar-EG', text: 'Arabic Egyptian (ar-EG)' },
          { value: 'zh', text: 'Chinese (zh)' }
        ],
        labels: {
          de: {
            labelHours: 'Stunden',
            labelMinutes: 'Minuten',
            labelSeconds: 'Sekunden',
            labelIncrement: 'Erhöhen',
            labelDecrement: 'Verringern',
            labelSelected: 'Ausgewählte Zeit',
            labelNoTimeSelected: 'Keine Zeit ausgewählt',
            labelCloseButton: 'Schließen'
          },
          'ar-EG': {
            labelHours: 'ساعات',
            labelMinutes: 'الدقائق',
            labelSeconds: 'ثواني',
            labelAmpm: 'صباحا مساء',
            labelAm: 'ص',
            labelPm: 'م',
            labelIncrement: 'زيادة',
            labelDecrement: 'إنقاص',
            labelSelected: 'الوقت المحدد',
            labelNoTimeSelected: 'لا وقت المختار',
            labelCloseButton: 'قريب'
          },
          zh: {
            labelHours: '小时',
            labelMinutes: '分钟',
            labelSeconds: '秒',
            labelAmpm: '上午下午',
            labelAm: '上午',
            labelPm: '下午',
            labelIncrement: '增量',
            labelDecrement: '减量',
            labelSelected: '选定时间',
            labelNoTimeSelected: '没有选择时间',
            labelCloseButton: '关'
          }
        }
      }
    },
    methods: {
      onContext(ctx) {
        this.context = ctx
      }
    }
  }
</script>

<!-- b-form-time-i18n.vue -->

Understanding the hourCycle

There are 2 main types of time keeping conventions (clocks) used around the world: the 12-hour clock and the 24-hour clock. The hourCycle property allows you to access the clock type used by a particular locale. The hour cycle type can have several different values, which are listed in the table below. The hourCycle signals how the time '00:00:00' (the start of the day) should be presented/formatted to a user of a particular locale. The 'context' event includes the resolved hourCycle value.

hourCycle Description
'h12' Hour system using 112. The 12 hour clock, with midnight starting at 12:00 am
'h23' Hour system using 023. The 24 hour clock, with midnight starting at 0:00
'h11' Hour system using 011. The 12 hour clock, with midnight starting at 0:00 am
'h24' Hour system using 124. The 24 hour clock, with midnight starting at 24:00

Native HTML5 <input type="date"> returns the time value in the 'h23' format, and <b-form-timepicker> also returns the v-model in the 'h23' format. This value may differ from what is presented to the user via the GUI (spin buttons) of the <b-form-timepicker> component, dependent upon the locale selected.

Note: IE 11 does not support resolving the hourCycle value of a locale, so we assume either h12 or h23 based on the resolved hour12 value.

Forcing 12 or 24 hour interface

12-hour versus 24-hour input is determined by the client browsers default locale (or the locale resolved from the locale prop). To force a 12-hour user interface, set the prop hour12 to true. To force a 24-hour user interface, set the prop hour12 to false. The default for prop hour12 is null which uses the resolved locale to determine which interface to use.

The setting of the hour12 prop will affect which hourCycle is resolved for formatting the hours spinbutton. Note that while this may affect the format of the hour spinbutton, but the formatted time string result may show the 'h12 or 'h23' format due to limitations in the client Intl.DateTimeFormat support for a particular locale. It is therefore recommended to leave the hour12 prop set to null (default), so show the locale default time/hour formatting.

Accessibility

The popup time supports the same keyboard controls as <b-time>, along with the following:

  • Esc will close the popup time without selecting a time

When internationalizing the timepicker, it is important to also update the label-* props with appropriate translated strings, so that international screen reader users will hear the correct prompts and descriptions.

Refer to the <b-time> documentation for additional details.

Implementation notes

<b-form-timepicker> is based upon the components <b-time> and <b-dropdown>.

<b-form-timepicker> uses Bootstrap's border and flex utility classes, along with button (btn-*) classes, dropdown (dropdown*) classes, and the form-control* (plus validation) classes. BootstrapVue's Custom SCSS/CSS is also required for proper styling of the time picker and popup.

See also

Component reference

<b-form-timepicker>

v2.6.0+

Component aliases

<b-form-timepicker> can also be used via the following aliases:

  • <b-timepicker>

Note: component aliases are only available when importing all of BootstrapVue or using the component group plugin.

Properties

All property default values are globally configurable.

Property
(Click to sort ascending)
Type
(Click to sort ascending)
Default
Description
aria-labelledby
StringThe ID of the element that provides a label for this component. Used as the value for the `aria-labelledby` attribute
boundary
HTMLElement or String'scrollParent'The boundary constraint of the menu: `'scrollParent'`, `'window'`, `'viewport'`, or a reference to an `HTMLElement`
button-only
v2.7.0+
BooleanfalseRenders the datepicker as a dropdown button instead of a form-control
button-variant
v2.7.0+
String'secondary'The button variant to use when in `button-only` mode. Has no effect if prop `button-only` is not set
close-button-variant
String'outline-secondary'Button variant to use for the optional `close` button
disabled
BooleanfalsePlaces the timepicker in a non-interactive disabled state
dropleft
BooleanfalseWhen set, positions the menu to the left of the button
dropright
BooleanfalseWhen set, positions the menu to the right of the button
dropup
BooleanfalseWhen set, positions the menu on the top of the button
footer-tag
String'footer'Specify the HTML tag to render instead of the default tag for the footer
form
StringID of the form that the form control belongs to. Sets the `form` attribute on the control
header-tag
String'header'Specify the HTML tag to render instead of the default tag for the header
hide-header
BooleanfalseWhen set, visually hides the selected time header
hour12
BooleannullTri-state prop. If `true` forces the interface to 12 hour format. If `false` forces the interface into 24 hour format. If `null` the current locale will determine the 12 or 24 hour interface (default)
id
StringUsed to set the `id` attribute on the rendered content, and used as the base to generate any additional element IDs as needed
label-am
String'AM'Text to display in the AM/PM spinbutton when 'AM' is selected
label-ampm
String'AM/PM'Value of the `aria-label` attribute on the `AM/PM` spinbutton
label-close-button
String'Close'Content for the `Close` button
label-decrement
String'Decrement'Value of the `aria-label` attribute on the spinbuttons `-` button
label-hours
String'Hours'Value of the `aria-label` attribute on the `Hours` spinbutton
label-increment
String'Increment'Value of the `aria-label` attribute on the spinbuttons `+` button
label-minutes
String'Minutes'Value of the `aria-label` attribute on the `Minutes` spinbutton
label-no-time-selected
String'No time selected'String to show when no time is selected
label-now-button
String'Select now'Content for the optional `Select now` button
label-pm
String'PM'Text to display in the AM/PM spinbutton when 'PM' is selected
label-reset-button
String'Reset'Content for the optional `Reset` button
label-seconds
String'Seconds'Value of the `aria-label` attribute on the `Seconds` spinbutton
label-selected
StringHidden sr-only string when a time is selected
locale
Array or StringLocale (or locales) for the component to use. When passing an array of locales, the order of the locales is from most preferred to least preferred. If not provided, defaults to the clients default locale
menu-class
Array or Object or StringClass (or classes) to apply to to popup menu wrapper
minutes-step
Number or String1Step value for the minutes spinbutton. Should be a value evenly divided into 60
name
StringSets the value of the `name` attribute on the form control
no-close-button
BooleanfalseWhen set, disables showing the close button
no-flip
BooleanfalsePrevent the menu from auto flipping positions
now-button
BooleanfalseWhen set, shows the optional `select now` button
now-button-variant
String'outline-primary'Button variant to use for the optional `select today` button
offset
Number or String0Specify the number of pixels to shift the menu by. Negative values supported
placeholder
StringText so show in the form control when no date is selected. Defaults to the `label-no-date-selected` prop value
popper-opts
Object{}Additional configuration to pass to Popper.js
readonly
BooleanfalsePlaces the timepicker in an interactive readonly state. Disables updating the v-model, while still allowing focusing of spin buttons
required
BooleanfalseWhen set, adds the `aria-required="true"` attribute on the component. Required validation needs to be handled by your application
reset-button
BooleanfalseWhen set, shows the optional `reset` button
reset-button-variant
String'outline-danger'Button variant to use for the optional `reset` button
reset-value
Date or StringWhen the optional `reset` button is clicked, the selected time will be set to this value. Default is to clear the selected value
right
BooleanfalseAlign the right edge of the menu with the right of the button
seconds-step
Number or String1Step value for the seconds spinbutton. Should be a value evenly divided into 60
show-seconds
BooleanfalseWhen true, shows the seconds spinbutton. If `false` the seconds spin button will not be shown and the seconds portion of the time will always be `0`
size
StringSet the size of the component's appearance. 'sm', 'md' (default), or 'lg'
state
BooleannullControls the validation state appearance of the component. `true` for valid, `false` for invalid, or `null` for no validation state
value
v-model
String''Initially selected time value. Accepts a `HH:mm:ss` string. Valid value ranges from `00:00:00` to `23:59:59`

v-model

Property
Event
valueinput

Slots

Name
Scoped
Description
button-content Content to place in the timepicker's icon button

Events

Event
Arguments
Description
context
  1. context - The `b-time` context object. See the `b-time` documentaion for details
`b-time` context event. Emitted when the user changes any spinbutton value via mouse or cursor control. Also emitted when the component is first instantiated, or the locale is changed
hidden v2.9.0+Emitted when the picker popup has hidden
input
  1. time - A string in the format of `HH:mm:ss` (24 hour format)
Emitted when updating the v-model
shown v2.9.0+Emitted when the picker popup has shown

Importing individual components

You can import individual components into your project via the following named exports:

Component
Named Export
Import Path
<b-form-timepicker>BFormTimepickerbootstrap-vue

Example:

import { BFormTimepicker } from 'bootstrap-vue'
Vue.component('b-form-timepicker', BFormTimepicker)

Importing as a Vue.js plugin

This plugin includes all of the above listed individual components. Plugins also include any component aliases.

Named Export
Import Path
FormTimepickerPluginbootstrap-vue

Example:

import { FormTimepickerPlugin } from 'bootstrap-vue'
Vue.use(FormTimepickerPlugin)