vue2-timepicker

Vue2 Timepicker

---

💡 Dead repo recharged in 2019 🔋

---

A dropdown time picker (hour|minute|second) for Vue 2.x, with flexible time format support.

Demo

You can see the Vue2 Timepicker in action in the Demo Page

Migration

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+)

Dependencies

Vue.js   

Installation

yarn add vue2-timepicker

npm install vue2-timepicker --save

NOTE: We stop Bower support from 0.2.0+, please check MIGRATION.md for migration guidelines.

Get Started

Step 1: Import VueTimepicker

Option A: Import component JS and CSS

// 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
// - 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
import 'vue2-timepicker/dist/VueTimepicker.css'

// Single File Component (the *.vue file with CSS included)
import VueTimepicker from 'vue2-timepicker/src/vue-timepicker.vue'

SSR Usage: Import the single file component for SSR Usage

// Import the *.vue file (CSS included)
// Note the `/sfc` suffix here
import VueTimepicker from 'vue2-timepicker/sfc'

Step 2: Include VueTimepicker in your component

var yourComponent = new Vue({
  components: { VueTimepicker },
  ...
})

Step 3: Put vue-timepicker in your component's template

Then, you can introduce the vue-timepicker tag anywhere you like in your component's template

<vue-timepicker></vue-timepicker>

Basic Usage

Base

<!-- Default to 24-Hour format HH:mm -->
<vue-timepicker></vue-timepicker>

Customized Time Format

<!-- Show seconds picker -->
<vue-timepicker format="HH:mm:ss"></vue-timepicker>

<!-- 12-hour format, with AM/PM picker -->
<vue-timepicker format="hh:mm A"></vue-timepicker>

<!-- 12-hour format, with seconds picker and am/pm picker -->
<vue-timepicker format="hh:mm:ss a"></vue-timepicker>

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"

Customized Picker interval

<!-- Show minute picker's value in the form of 0, 5, 10, ... 55, 60 -->
<vue-timepicker :minute-interval="5"></vue-timepicker>

<!-- Show second picker's value in the form of 0, 10, 20, ... 50, 60 -->
<vue-timepicker :second-interval="10"></vue-timepicker>

<!-- Bind interval config with your own data variable -->
<vue-timepicker :minute-interval="yourMinuteInterval"></vue-timepicker>

Data Binding

Bind Value with v-model

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:

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.

<!-- Object form -->
<vue-timepicker v-model="yourTimeValue" format="HH:mm:ss"></vue-timepicker>

<!-- String form -->
<vue-timepicker v-model="yourStringTimeValue" format="HH:mm:ss"></vue-timepicker>

Set Empty Initial Value

When the initial value is completely unknown:

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:

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'
  }
}

<!-- OBJECT FORM -->
<!-- Default 24-Hour -->
<vue-timepicker v-model="timeValue"></vue-timepicker>
<!-- 12-Hour with seconds -->
<vue-timepicker v-model="timeValueWithSec" format="h:mm:ss A"></vue-timepicker>

<!-- STRING FORM -->
<!-- Default 24-Hour + String value -->
<vue-timepicker v-model="stringTimeValue"></vue-timepicker>
<!-- 12-Hour with seconds + String value -->
<vue-timepicker v-model="stringTimeValueWithSec" format="h:mm:ss A"></vue-timepicker>

Get Time Picker's Current Value

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.

<vue-timepicker v-model="yourTimeValue" format="HH:mm:ss" @input="inputHandler"></vue-timepicker>

{
  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.

// In `inputHandler`:
// console.log outputs -> {HH: "14", mm: "30", ss: "15"}

Read Data From change Event

<!-- A: No argument -->
<vue-timepicker v-model="yourTimeValue" @change="changeHandler"></vue-timepicker>

<!-- B: Custom arguments -->
<vue-timepicker v-model="yourTimeValue" @change="otherChangeHandler($event, 'foo', 42)"></vue-timepicker>

// 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:

// `@change` event data
{
  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 `displayTime` added since v0.2.2
  displayTime: "14:30:15"
}

Whereas the v-model / input only return the data with defined tokens

// Previously defined variable (`yourTimeValue` in this case) as {HH:..., mm:..., ss:...}
// Hence, the `v-model` returns:
{
  HH: "14",
  mm: "30",
  ss: "15"
}

Advance Usage

Hide Clear Button

<vue-timepicker hide-clear-button></vue-timepicker>

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.

Disable Picker

<vue-timepicker disabled></vue-timepicker>

Fully disable both dropdown picker and the "×" clear button in the UI, to prevent users from changing any values again.

Define Hour Range

Sometimes you may want to limit hours picker to a specific range. The hour-range parameter is here to help.

<!-- 24-Hour Format -->
<vue-timepicker :hour-range="[5, [8, 12], [14, 17], 19]"></vue-timepicker>
<!-- >> Equals to :hour-range="[5, 8, 9, 10, 11, 12, 14, 15, 16, 17, 19]" -->

<!-- 12-Hour Format -->
<vue-timepicker :hour-range="['7a', '9a', '11a', '1p', ['3p', '5p'], '7p']" format="hh:mm a">
<!-- >> Equals to :hour-range="['7a', '9a', '11a', '1p', '3p', '4p', '5p', '7p']" -->

Hide Disabled Hour Ranges

<vue-timepicker :hour-range="[5, [8, 12], [14, 17], 19]" hide-disabled-hours></vue-timepicker>

It's a pair with the above hour-range parameter. In this sample, 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.

Enable Debug Mode

<vue-timepicker debug-mode></vue-timepicker>

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" as an example --

<!-- Manual Bug Sample: Define timepicker with format "h:mm:ss A" -->
<vue-timepicker v-model="yourStringValue" format="h:mm:ss A" debug-mode></vue-timepicker>

{
  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:

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

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
hour-range	Array	no	undefined
hide-disabled-hours	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
input-class	String	no	undefined

Timepicker now supports id, name, and placeholder like common form elements. Values will be assigned to the <input type="text" class="display-time"> within the component.

Input id And name

<!-- id -->
<vue-timepicker id="myFirstPicker"></vue-timepicker>

<!-- name -->
<vue-timepicker name="nameInForm"></vue-timepicker>

Input placeholder

When placeholder is undefined, timepicker takes the determined format string instead.

<!-- placeholder is set -->
<vue-timepicker placeholder="Start Time"></vue-timepicker>
<!-- -> "Start Time" -->

<!-- placeholder not set -->
<vue-timepicker format="hh:mm A"></vue-timepicker>
<!-- -> "hh:mm A" -->

<!-- both placeholder and format are not set -->
<vue-timepicker></vue-timepicker>
<!-- -> "HH:mm" -->

The input-class

The input-class is assigned to the text input within the component as well.

<!-- Set your own `input-class` in the Vue template -->
<vue-timepicker input-class="my-awesome-picker"></vue-timepicker>

<!-- HTML result -->
<span class="vue__time-picker time-picker">
  <input class="display-time my-awesome-picker" type="text" readonly="readonly">
  <!-- ... -->
</span>

Events API

Event	Arguments	Description
input	(value)	Emit after value changes
change	(eventData)	Emit after value changes
open		Emit when the dropdown opens
close		Emit when the dropdown closes

The open and close Event of the Dropdown Picker

Help to identify the current status of the dropdown picker

// Define a variable for logging the status
data () {
  return {
    dropdownStatus: 'closed'
  }
}

<p>Dropdown Status: I'm {{dropdownStatus}}!</p>

<vue-timepicker @open="dropdownStatus = 'opened'" @close="dropdownStatus = 'closed'"></vue-timepicker>

Contribution

Please feel free to fork and help developing. Check CONTRIBUTING.md for more details.

Change Log

Detail changes of each release: CHANGELOG.md

License

MIT