A dropdown time picker (hour|minute|second) for Vue 2.x, with flexible time format support
npm install vue2-timepicker!GitHub version
!npm version
!GitHub release
!npm downloads
---
π‘ Dead repo recharged π
---
A dropdown time picker (hour|minute|second) for Vue 2.x, with flexible time format support.
You can see the Vue2 Timepicker in action in the Demo Page
Please check MIGRATION.md for basic guidelines if you are about to:
- Migrate from the Vue 1.x version vue-time-picker
- Migrate from Bower to Yarn or NPM (Vue2 Timepicker v0.1.x -> v0.2.0+)
Vue.js !npm peer dependency version
``bash`
yarn add vue2-timepicker
`bash`
npm install vue2-timepicker --save
> NOTE: We stop Bower support from 0.2.0+, please check MIGRATION.md for migration guidelines.
#### Option A: Import component JS and CSS
`javascript
// Main JS (in UMD format)
import VueTimepicker from 'vue2-timepicker'
// CSS
import 'vue2-timepicker/dist/VueTimepicker.css'
`
#### Option B: Choose any bundle version base on your needs
Javascript
`javascript`
// CommonJS
import VueTimepicker from 'vue2-timepicker/dist/VueTimepicker.common.js'
// UMD
import VueTimepicker from 'vue2-timepicker/dist/VueTimepicker.umd.js'
// UMD Minified
import VueTimepicker from 'vue2-timepicker/dist/VueTimepicker.umd.min.js'
CSS
`css
@import 'vue2-timepicker/dist/VueTimepicker.css';
/ Or, with node_module alias path like: /
@import '~vue2-timepicker/dist/VueTimepicker.css';
/*
NOTE: the path alias to node_modules differs between bundlers.~
Please change the to any alias that works with your environment.`
*/
Single File Component
`javascript`
// The *.vue file with CSS included
import VueTimepicker from 'vue2-timepicker/src/vue-timepicker.vue'
// NOTE: In some cases, it requires additional workarounds in the bundler's config
#### SSR Usage
`javascript/sfc
// Import the *.vue file (CSS included)
import VueTimepicker from 'vue2-timepicker/sfc'
// Note the suffix here`
If your server-side renderer cannot recognize the /sfc alias, please try --
`javascript/src
// Manually point to the folder`
import VueTimepicker from 'vue2-timepicker/src'
// Or, to the specific file name
import VueTimepicker from 'vue2-timepicker/src/vue-timepicker.vue'
`javascript`
var yourComponent = new Vue({
components: { VueTimepicker },
...
})
Then, you can introduce the vue-timepicker tag anywhere you like in your component's template
`html`
`html`
`html
`
VueTimepicker recognizes the following tokens in the format string
Section | Token | Output
---------- | ----- | ---------------
AM/PM | A | AM PM
| a | am pm
Hour | H | 0 1 ... 22 23
| HH | 00 01 ... 22 23
| h | 1 2 ... 11 12
| hh | 01 02 ... 11 12
| k | 1 2 ... 23 24
| kk | 01 02 ... 23 24
Minute | m | 0 1 ... 58 59
| mm | 00 01 ... 58 59
Second | s | 0 1 ... 58 59
| ss | 00 01 ... 58 59
> If not set, the format string is default to "HH:mm"
`html
`
From v1.0.0+, timepicker's v-model accepts value in both _Object_ (default) and _String_ format. The v0.x versions only support _Object_ form.
#### Set Initial Value
For example, if you want to set "10:05:00" ("HH:mm:ss" format) as the initial value of vue-timepicker:
`javascript`
const yourComponent = new Vue({
components: { VueTimepicker },
data () {
return {
// Object form
yourTimeValue: {
HH: '10',
mm: '05',
ss: '00'
},
// String form
yourStringTimeValue: '10:05:00',
...
}
},
...
})
Both forms lead to the same result.
`html
`
#### Set Empty Initial Value
When the initial value is completely unknown:
`javascript
data () {
return {
// Will be rendered as Object form
yourEmptyValue: {},
emptyValueToo: undefined,
emptyValueAsWell: null,
// Will be taken into String form
yourEmptyStringValue: ''
}
}
`
#### Set Partially-Known Initial Value
For instance, if you want to set the initial hour value to 8 pm and leave the rest slots empty:
`javascript
data () {
return {
// OBJECT FORM
// Default 24-Hour
timeValue: {
HH: '20',
mm: ''
},
// 12-Hour with seconds
timeValueWithSec: {
h: '8',
mm: '',
ss: '',
A: 'PM'
},
// STRING FORM
// Default 24-Hour + String value
stringTimeValue: '20:mm',
// 12-Hour with seconds + String value
stringTimeValueWithSec: '8:mm:ss PM'
}
}
`
`html
`
#### Get value from v-model
You can either read the binding v-model value anytime or add a handler to deal with the input event from vue-timepicker.
`html`
`javascript
{
data () {
return {
yourTimeValue: {
HH: '10',
mm: '05',
ss: '00'
},
...
}
},
methods: {
inputHandler (eventData) {
console.log(eventData)
}
}
}
`
In this case, we set the initial value (_yourTimeValue_) to "10:05:00". Then, open the dropdown picker and pick a new time, like setting it to "14:30:15" for example.
`javascriptinputHandler
// In :`
// console.log outputs -> {HH: "14", mm: "30", ss: "15"}
`html
`
`javascript
// A: No argument
changeHandler (eventData) {
console.log(eventData)
// -> {data: {HH:..., mm:... }, displayTime: "HH:mm"}
}
// B: Custom arguments
otherChangeHandler (eventData, yourArg1, yourArg2) {
console.log(eventData)
// -> {data: {HH:..., mm:... }, displayTime: "HH:mm"}
console.log(yourArg1)
// -> 'foo'
console.log(yourArg2)
// -> 42
}
`
Unlike v-model and input event, which only return the defined time tokens you provided in the binding variable, the change event delivers all supported formats.
In the example above, after the user set values to "14:30:15" in the picker, change event returns the following data:
`javascript@change
// event datadisplayTime
{
data: {
HH: "14",
H: "14",
hh: "14",
a: "am",
A: "AM",
h: "14",
kk: "14",
k: "14",
m: "30",
mm: "30",
s: "15",
ss: "15"
},
// extra added since v0.2.2`
displayTime: "14:30:15"
}
Whereas the v-model / input only return the data with defined tokens
`javascriptyourTimeValue
// Previously defined variable ( in this case) as {HH:..., mm:..., ss:...}v-model
// Hence, the returns:`
{
HH: "14",
mm: "30",
ss: "15"
}
`html`
Enable to hide the "×" clear button on the right-hand side. Users can still pick new values from the dropdown, but they cannot erase any selected data.
`html`
Fully disable both dropdown picker and the "×" clear button in the UI, to prevent users from changing any values again.
Automatically close the dropdown when the user finishes selecting all of the required fields.
`html`
`html`
Auto-scroll to selected values on dropdown open. It works with both:
- Programmatically defined value. E.g., the initial value from v-model
- Values manually picked by the user.
Sometimes you may want to limit hours picker to a specific range. The hour-range parameter is here to help.
`html
`
Similar to hour-range, you can determine values in the minutes and seconds dropdown by using minute-range and second-range.
`html
`
When implemented together with minute-interval and second-interval, the customized intervals take the priority.
`html
`
There're four kinds of helper properties to let you hide the values excluded by hour-range, minute-range, and second-range.
- hide-disabled-items: Hide all disabled items - hour, minute, and seconds.
- hide-disabled-hours: Hide disabled hour values only.
- hide-disabled-minutes: Hide disabled minute values only.
- hide-disabled-seconds: Hide disabled second values only.
`html`
Here we take the hide-disabled-hours as an example. It's a pair with the hour-range parameter. In this case, the hour picker hides the invalid hours (_0, 1, 2, 3, 4, 6, 7, 13, 18, 20, 21, 22, 23_) and display the valid hours (_5, 8, 9, ..._) only.
Basic keyboard support includes:
- Tab: Focus or blur the Timepicker
- Esc: Close the dropdown
Advance Keyboard support (enabled with advanced-keyboard):
- Arrow Keys: Navigate between valid (non-disabled) values and columns
- Space or Enter: Select the focusing item
`html`
Please be aware that after putting the advanced-keyboard on, hundreds of additional keyboard event listeners are going to be attached to the component. The amount of listeners depends on how many hours, minutes, and seconds value you enabled in the current Timepicker.
`html`
Sets the blur delay time for the dropdown. Defaults to 300 if not set.
`html`
Let users add or change values through the box besides the dropdown picker.
`html`
Works with manual-input mode. It sets the timeout for continuous input. Defaults to 1000 if not set.
How It Works?
For example, when a user focuses on the hour slot (HH) of a "HH:mm" formatted Timepicker (with the default value 1000):
- Case 1: User first inputs 1, and then inputs 2 _500ms_ later -> Timepicker takes 12 as the final value and set it to the "HH" slot.1
- Case 2: User inputs , and then presses the key 2 _1200ms_ later -> Timepicker takes 2 as the final value and set it to 02 for the "HH" slot.
> NOTE: To use this feature, you MUST ENABLE the manual-input mode _(v.1.1.0+)_ in the first place.
It makes the dropdown picker hidden by default.
`html`
Users can still choose to open the dropdown by clicking the triangle ("▾") button on the right. _(v.1.1.3+)_
`html`
Make the dropdown button always visible in the UI. _(v.1.1.4+)_
Change dropdown direction when needed _(v.1.1.5+)_. Accepting values:
- down: Default value.
- up: Force open the dropdown above the input.
- auto: Auto detects available height and opens the dropdown on top if there are not enough spaces below the input.
`html
`
#### Container ID
Works with drop-direction="auto". It defines the parent container where the timepicker should calculate the free spaces from. If this value is not set, timepicker will watch document.body instead.
` html`
#### Drop Offset Height
Works with drop-direction="auto" either. Defaults to 160 (unit: _px_) if the value is not set.
`html`
`html`
When lazy event mode is toggled on, only an actual user behavior can trigger the input and change events. Which are:
- The user opened the dropdown and picked a new value
- The user clicked the ("×") clear button
- The user inputted a new value or clear the existing value in the Manual Input mode
In other words, on lazy mode, Timepicker won't emit input and change events on mounted, nor after the value got modified programmatically.
Append the dropdown menu to the end of the document
. Try this if you have z-index or overflow layout issue with the dropdown.`html
`The body-appended dropdown's CSS class is
vue__time-picker-dropdown. Its default z-index is 100. You can change the value by adding the following style in your app -- `css
/ E.g. set the z-index to 5000 /
.vue__time-picker-dropdown {
z-index: 5000;
}
`NOTE: If you have to override some of the CSS styles within the dropdown, you will need to update their selectors' class names as well. Simply change any
.vue__time-picker .dropdown selector to .vue__time-picker-dropdown.For example, when you have a customized background color set for selected values:
`css
/ Default override (not using "append-to-body") /
.vue__time-picker .dropdown ul li:not([disabled]).active {
background: steelblue;
}/ When using "append-to-body" /
.vue__time-picker-dropdown ul li:not([disabled]).active {
background: steelblue;
}
`$3
`html
`It's aimed to help developers to investigate the input -> output process. When debug mode is toggled on, you can see extra
DEBUG: ... logs coming through the console window as you interact with the vue-timepicker.Let's create a "bug" here as an example --
`html
``javascript
{
data () {
return {
// Manual Bug Sample:
// Should be '3:mm:05 A' but oops.. the finger slipped
yourStringValue: 'e:mm:05 A'
}
}
}
`Then, in the console window, you should see a debug log saying:
`console
DEBUG: The input string in "v-model" does NOT match the "format" pattern
format: h:mm:ss A
v-model: e:mm:05 A
`Main Props API Overview
Prop | Type | Required | Default Value
------------------------- | ------------------ | -------- | -------------
v-model | _Object_, _String_ | no | _undefined_
format | _String_ | no | "HH:mm"
minute-interval | _Number_ | no | _undefined_
second-interval | _Number_ | no | _undefined_
hide-clear-button | _Boolean_ | no | false
disabled | _Boolean_ | no | false
close-on-complete | _Boolean_ | no | false
auto-scroll | _Boolean_ | no | false
hour-range | _Array_ | no | _undefined_
minute-range | _Array_ | no | _undefined_
second-range | _Array_ | no | _undefined_
hide-disabled-hours | _Boolean_ | no | false
hide-disabled-minutes | _Boolean_ | no | false
hide-disabled-seconds | _Boolean_ | no | false
hide-disabled-items | _Boolean_ | no | false
advanced-keyboard | _Boolean_ | no | false
blur-delay | _Number_ | no | 300
manual-input | _Boolean_ | no | false
manual-input-timeout | _Number_ | no | 1000
hide-dropdown | _Boolean_ | no | false
fixed-dropdown-button | _Boolean_ | no | false
drop-direction | _String_ | no | "down"
container-id | _String_ | no | _undefined_
drop-offset-height | _Number_ | no | 160
lazy | _Boolean_ | no | false
append-to-body | _Boolean_ | no | false
debug-mode | _Boolean_ | no | false
Input Props API
Prop | Type | Required | Default Value
------------------| --------------------------- | -------- | -------------
id | _String_ | no | _undefined_
name | _String_ | no | _undefined_
placeholder | _String_ | no | _undefined_
tabindex | _Number_ | no | 0
autocomplete | _String_ | no | 'off'
input-class | _String_, _Array_, _Object_ | no | _undefined_
input-width | _String_ | no | '10em'
Timepicker supports
id, name, placeholder, and tabindex like common form elements. These values are assigned to the within the component.$3
`html
`$3
When
placeholder is undefined, timepicker takes the determined format string instead.`html
`$3
> NOTE: To use this property, you MUST ENABLE the
manual-input mode _(v.1.1.0+)_ in the first place.`html
``html
`When enabled, it accepts any string value supported by the HTML input
autocomplete attribute. The value is assigned to the embedding text , which means it follows form autofill rules and configs set in the browser level. For example, most of the browsers require the input to have a name and/or id attribute. Some browsers, like Firefox, demand the input to be a descendant of a