Time

BootstrapVue's custom <b-time> component generates a WAI-ARIA compliant time selection widget, which can be used to control other components, or can be used to create customized time picker inputs.

Available in BootstrapVue since v2.6.0

Overview

<b-time> is WAI-ARIA accessibility compliant, optimized for keyboard control (arrow, page up/down, home, and end keys). Internationalization is also supported, and default's to the browser's or page's locale, if no locale(s) are specified.

If you need a time picker as a custom form control input, use the <b-form-timepicker> component instead.

<template>
  <b-row>
    <b-col md="auto">
      <b-time v-model="value" locale="en" @context="onContext"></b-time>
    </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
      }
    },
    methods: {
      onContext(ctx) {
        this.context = ctx
      }
    }
  }
</script>

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

v-model return value

<b-time> 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-time> returns an empty string ('').

Disabled and readonly states

Setting the disabled prop will remove all interactivity of the <b-time> component. Setting the readonly prop will disable selecting a time, but will keep the spinbuttons focusable.

<template>
  <div>
    <b-form-group
      label="Select time 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-time
      id="ex-disabled-readonly"
      :disabled="disabled"
      :readonly="readonly"
    ></b-time>
  </div>
</template>

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

<!-- b-time-disabled-readonly.vue -->

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>
  <b-time v-model="value" show-seconds locale="en"></b-time>
  <div class="mt-2">Value: '{{ value }}'</div>
</template>

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

<!-- b-time-show-seconds.vue -->

Hiding the top selected time header

By default, the current selected time will be displayed at the top of the time component, formatted in the locale's language.

You can hide this header via the hide-header prop. Note this only visually hides the selected time, while keeping it available to screen reader users as an aria-live region.

Border and padding

Fancy a time control with a border with padding? Use Bootstrap's border and padding utility classes to add borders and padding:

<template>
  <b-time class="border rounded p-2" locale="en"></b-time>
</template>

<!-- b-time-border-padding.vue -->

Default slot

Provide optional content at the bottom of the time interface via the use of default slot. The slot can be used to add buttons such as Now or Reset, etc.

<template>
  <b-time v-model="value" show-seconds locale="en">
    <div class="d-flex" dir="ltr">
      <b-button
        size="sm"
        variant="outline-danger"
        v-if="value"
        @click="clearTime"
      >
        Clear time
      </b-button>
      <b-button
        size="sm"
        variant="outline-primary"
        class="ml-auto"
        @click="setNow"
      >
        Set Now
      </b-button>
    </div>
  </b-time>
</template>

<script>
  export default {
    data() {
      return {
        value: null
      }
    },
    methods: {
      setNow() {
        const now = new Date()
        // Grab the HH:mm:ss part of the time string
        this.value = now.toTimeString().slice(0, 8)
      },
      clearTime() {
        this.value = ''
      }
    }
  }
</script>

<!-- b-time-default-slot.vue -->

Events

input event

The 'input' event is emitted when updating the v-model. The event has a single argument which is the selected time as a string. The value is a string in the format of 'HH:mm:ss' (or an empty string if no time is selected). Valid values are in the range of '00:00:00' through 23:59:59'.

If fhe show-seconds prop is not set, the seconds portion of the time value will always be '00'.

If the disabled or readonly props are set, the 'input' event will not be emitted.

context event

The 'context' event is emitted whenever a user selects a time, or the user changes a value of one of the spinbuttons. It will also be emitted when the component is created (just before insertion into the DOM), or when the resolved locale has changed.

The event will not be emitted when the disabled or readonly props are set (except for the initial emit when the time component is created).

The 'context' event is passed a context object as it's only argument, with the following properties:

Property Description
value The current value as an HH:mm:ss string or an empty string '' if no time selected
formatted The current value formatted in the resolved locale, or the label-no-time prop value if no time selected
hours The currently selected hour (always 24 hour, h23' format) as a number or null if no hour
minutes The currently selected minute value as a number or null if no minute
seconds The currently selected seconds value as a number or null if no seconds
locale The locale resolved by the time picker, this may be different than the requested locale
isRTL Will be true is the locale is RTL (right-to-left)
hour12 Boolean value indicating if the interface is using 12 hour format
hourCycle A string representing the type of hour cycle used for the spinbuttons: 'h11', 'h12', 'h23' or 'h24'

Refer to the Internationalization section for information on the context properties locale, hour12 and hourCycle.

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-time> 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="auto">
      <b-time
        v-model="value"
        v-bind="labels[locale] || {}"
        :locale="locale"
        show-seconds
        @context="onContext"
      ></b-time>
    </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'
          },
          'ar-EG': {
            labelHours: 'ساعات',
            labelMinutes: 'الدقائق',
            labelSeconds: 'ثواني',
            labelAmpm: 'صباحا مساء',
            labelAm: 'ص',
            labelPm: 'م',
            labelIncrement: 'زيادة',
            labelDecrement: 'إنقاص',
            labelSelected: 'الوقت المحدد',
            labelNoTimeSelected: 'لا وقت المختار'
          },
          zh: {
            labelHours: '小时',
            labelMinutes: '分钟',
            labelSeconds: '秒',
            labelAmpm: '上午下午',
            labelAm: '上午',
            labelPm: '下午',
            labelIncrement: '增量',
            labelDecrement: '减量',
            labelSelected: '选定时间',
            labelNoTimeSelected: '没有选择时间'
          }
        }
      }
    },
    methods: {
      onContext(ctx) {
        this.context = ctx
      }
    }
  }
</script>

<!-- b-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-time> 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-time> 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

<b-time> provides many accessibility features, such as aria-live regions, roles, aria labeling, shortcut keys and full keyboard navigation to work with most screen readers.

Keyboard navigation:

  • ArrowUp Increments the currently selected spinbutton value
  • ArrowDown Decrements the currently selected spinbutton value
  • Home Sets the selected spinbutton to the minimum value
  • End Sets the selected spinbutton to the maximum value
  • PageUp Increases the selected spinbutton value by the spinbutton's step by a larger value
  • PageDown Decreases the selected spinbutton value by the spinbutton's step by a larger value
  • ArrowRight Moves focus to the next spin button in the component
  • ArrowLeft Moves focus to the previous spin button in the component

Several of the label-* props are not visible on screen, but are used to label various elements within the calendar for screen reader users. e.g. the label-selected prop is added to the element that displays the selected value.

When internationalizing the datepicker, 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.

Implementation notes

The <b-time> component is based upon the custom BootstrapVue component <b-form-spinbutton>.

<b-time> uses Bootstrap's border and flex utility classes, along with button (btn-*) classes and the form-control class. BootstrapVue's custom SCSS/CSS is also required for proper styling.

See also

Component reference

<b-time>

v2.6.0+

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
disabled
BooleanfalseWhen set to `true`, disables the component's functionality and places it in a disabled state
footer-tag
v2.22.0+
String'footer'Specify the HTML tag to render instead of the default tag for the footer
header-tag
v2.22.0+
String'header'Specify the HTML tag to render instead of the default tag for the footer
hidden
Booleanfalse
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-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-pm
String'PM'Text to display in the AM/PM spinbutton when 'PM' is selected
label-seconds
String'Seconds'Value of the `aria-label` attribute on the `Seconds` spinbutton
label-selected
String'Selected time'Hidden 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
minutes-step
Number or String1Step value for the minutes spinbutton. Should be a value evenly divided into 60
readonly
BooleanfalseSets the `readonly` attribute on the form control
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`
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
Description
default Used to place custom controls at the bottom of the time component

Events

Event
Arguments
Description
context
  1. context - The context object. Refer to the docs for details
Emitted whenever the internal model state, or locale, updates. Also emitted when the component is initially created
input
  1. value - The selected time as an `HH:mm:ss` string. Will be an empty string if no time selected
Event that updates the v-model

Importing individual components

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

Component
Named Export
Import Path
<b-time>BTimebootstrap-vue

Example:

import { BTime } from 'bootstrap-vue'
Vue.component('b-time', BTime)

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
TimePluginbootstrap-vue

Example:

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