timepicker-ui
timepicker-ui is an easy library with timepicker. Fully wrote with TypeScript. This library is based on Material Design from Google.
- Free
- Easy to use
- Easy to customize
Click here to see a demo and examples
Desktop version
24h version
Landspace version
Mobile version
Themes
There is 3 available version of theme: crane-straight, crane-radius and m3.
Theme m3
based on the new Material Design v3. Material Design 3 is still not release in offical version for WEB but you can use it if you want.
There is new version of Material Design 3.
If new version M3 will be released this design will get improve.
Desktop
Landspace
Mobile
Theme m3
Theme m3-mobile
Installation
Install timepicker-ui in your project.
Yarn
$ yarn add timepicker-ui
NPM
$ npm install timepicker-ui
This library is using font Roboto and material-design icons. Basic options for all icons have been taken from material-icons. If you want to use material-icons you have to add dependencies to your project.
You can alawys change icons to another package if you change options iconTemplate
and iconTemplateMobile
which contains templates for icons. iconTemplate
and iconTemplateMobile
requiare default class timepicker-ui-keyboard-icon
.
Usage
Styles
We provide CSS styles built-in but sometimes if you don't use some normalize/reset CSS styles you have to add box-sizing: border-box
to your app to display the correct layout.
*,
::after,
::before {
box-sizing: border-box;
}
ES Modules
In your project you have to import timepicker from package to your JavaScript file.
import { TimepickerUI } from "timepicker-ui";
UMD
In your html file you have put script tag with path to timepicker-ui.umd.js
file. After installing by npm/yarn you can copy the file from node_modules or add a path to this file.
<script src="timepicker-ui.umd.js"></script>
<script src="node_modules/path/timepicker-ui.umd.js"></script>
<script src="/path/timepicker-ui.umd.js"></script>
Information
timepicker-ui has to have a wrapper that has an input inside this wrapper. If you will not add class timepicker-ui
to your wrapper, it will be automatically added during initialization.
HTML
<div class="timepicker-ui">
<input type="text" class="timepicker-ui-input" value="12:00 AM" />
</div>
timepicker-ui has to be created with a new instance with key new
. This instance accepts two parameters which first is the wrapper element for timepicker and the second is options that allow customization.
JavaScript
const DOMElement = document.querySelector(".timepicker-ui");
const options = {};
const newTimepicker = new TimepickerUI(DOMElement, options);
By default initialization of timepicker is started when you click on input. If you want to change it you have to add data-open
attribute with selector inside and this element has to be inside wrapper.
To initalize a timepicker with UMD version you have to init a window object with tui
.
const DOMElement = document.querySelector(".timepicker-ui");
const options = {};
const newTimepicker = new window.tui.TimepickerUI(DOMElement, options);
newTimepicker.create();
HTML
<div class="default-class">
<input type="text" class="timepicker-ui-input" value="12:00 AM" />
<button class="timepicker-ui-button" data-open="default-class">Open</button>
</div>
JavaScript
const timepicker = document.querySelector(".default-class");
const initTimepicker = new TimepickerUI(timepicker);
timepicker.create();
Options
You can set options by JavaScript or by data-attribute which attribute
is a key option. Data-attributes will be overridden by JavaScript options.
HTML
<div
class="default-class"
data-am-label="test"
data-backdrop="false"
data-ok-label="fine"
>
<input type="text" class="timepicker-ui-input" value="12:00 AM" />
<button class="timepicker-ui-button" data-open="default-class">Open</button>
</div>
JavaScript
const timepicker = document.querySelector(".default-class");
const options = { okLabel: "test", amLabel: "test1", backdrop: false };
const initTimepicker = new TimepickerUI(timepicker, options);
timepicker.create();
CDNJS
This library is aviable in cdnjs packages. Here is a link to the full description https://cdnjs.com/libraries/timepicker-ui.
You can put script tags in your HTML file and use UMD version, without installation.
<script
src="https://cdnjs.cloudflare.com/ajax/libs/timepicker-ui/2.3.0/timepicker-ui.umd.js"
integrity="sha512-a3QUlKZYbhDBhA0b++tX+QjrbEwk1DNTyCR7rzwM34AUx16sNOLDzh4JQhqV5xYLs010+xsnFjrDjz2jx2+qLw=="
crossorigin="anonymous"
referrerpolicy="no-referrer"
></script>
React integration
It is possible to use this library on the React application. It's necessary to use the useRef hook to attach a dom element and add a custom event handler to this ref.
Link to an example with React Hooks.
Link to an example with React Class Component.
import React, { useRef, useEffect, useState, useCallback } from 'react';
import { TimepickerUI } from 'timepicker-ui';
function App(): JSX.Element {
const tmRef = useRef(null);
const [inputValue, setInputValue] = useState('12:00 PM');
const testHandler = useCallback((e: CustomEvent) => {
setInputValue(`${e.detail.hour}:${e.detail.minutes} ${e.detail.type}`);
}, []);
useEffect(() => {
if (inputValue === "10:00 PM") {
alert("You selected 10:00 PM");
}
}, [inputValue]);
useEffect(() => {
const tm = (tmRef.current as unknown) as HTMLDivElement;
const newPicker = new TimepickerUI(tm, {});
newPicker.create();
//@ts-ignore
tm.addEventListener('accept', testHandler);
return () => {
//@ts-ignore
tm.removeEventListener('accept', testHandler);
};
}, [testHandler]);
return (
<div className='timepicker-ui' ref={tmRef}>
<input
type='test'
className='timepicker-ui-input'
defaultValue={inputValue}
/>
</div>
);
}
export default App;
Vue integration
This library can be used on Vue too. You have to use this.$refs to attach elements on DOM and add a custom event listener to this element.
Link to an example with Vue 2
Link to an example with Vue 3
<template>
<div class="hello">
<div class="timepicker-ui" ref="tm">
<input v-model="inputValue" type="text" class="timepicker-ui-input" />
</div>
{{ inputValue }}
</div>
</template>
<script>
import { TimepickerUI } from "timepicker-ui";
export default {
name: "HelloWorld",
data() {
return {
inputValue: "10:10 PM",
};
},
mounted() {
const test = new TimepickerUI(this.$refs.tm, { enableSwitchIcon: true });
test.create();
this.$refs.tm.addEventListener("accept", ({ detail }) => {
this.inputValue = `${detail.hour}:${detail.minutes} ${detail.type}`;
});
},
};
</script>
Table with options
Name | Default | Type | Description |
---|---|---|---|
animation | true | boolean | Turn on/off animations on picker on start/close |
amLabel | AM | string | You can set custom text to am label |
appendModalSelector | '' | string | You can set default selector to append timepicker inside it. Timepicker default append to body |
backdrop | true | boolean | Turn on/off backdrop |
cancelLabel | CANCEL | string | You can set custom text to cancel button |
clockType | 12h | string | You can set type of clock, it contains 2 versions: 12h and 24h. |
editable | false | boolean | Edit hour/minutes on the web mode. |
enableScrollbar | false | boolean | Turn on/off scroll if timepicker is open |
enableSwitchIcon | false | boolean | Turn on/off icon to switch desktop/mobile |
focusInputAfterCloseModal | false | boolean | Turn on/off focus to input after close modal |
focusTrap | true | boolean | Turn off/on focus trap to the picker |
hourMobileLabel | Hour | string | You can set custom text to hour label on mobile version |
incrementHours | 1 | nubmer | Increment hour by 1, 2, 3 hour |
incrementMinutes | 1 | nubmer | Increment minutes by 1, 5, 10, 15 minutes |
minuteMobileLabel | Minute | string | You can set custom text to minute label on mobile version |
mobile | false | boolean | Turn on mobile version |
mobileTimeLabel | Enter Time | string | You can set custom text to time label on mobile version |
okLabel | OK | string | You can set custom text to ok label |
pmLabel | PM | string | You can set custom text to pm label |
timeLabel | Select Time | string | You can set custom text to time label on desktop version |
switchToMinutesAfterSelectHour | true | boolean | Turn on/off switch to minutes by select hour |
iconTemplate | <i class="material-icons timepicker-ui-keyboard-icon"> keyboard </i> | string | You can set default template to switch desktop.This options is using by default material design icon |
iconTemplateMobile | <i class="material-icons timepicker-ui-keyboard-icon"> schedule </i> | string | You can set default template to switch mobile. This options is using by default material design icon |
theme | basic | string | You can set theme to timepicker. Available options: basic, crane-straight, crane-radius and m3. The offical version of Material Design 3 is still not avaialbe for the WEB version. Theme m3 has been added based on the design what you can find here. If new version M3 will be released this design will get improve.
|
disabledTime | undefined | object | This option allows 3 keys: hours , minutes and interval . The hours and minutes are arrays which accept strings and numbers to block select hours/minutes. The interval key allow only string with interval values i.e., if you have 24h clockType the string can be 03:00 - 15:00, 01:20 - 05:15, 02:03 - 06:55 etc.. On the other hand if you have 12h clockType the string can be i.e 01:30 PM - 6:30 PM, 02:00 AM - 10:00 AM, 02:30 AM - 10:30 PM. It is important to remember that first hour in the interval option should be less that the second value if you want to block values from AM to PM and if you are using interval with 24h clockType. If the interval key is set, the hours/minutes keys are ignored.
|
currentTime | undefined | boolean | object |
Set current time to the input and timepicker. If this options is set to true it's gonna update picker with toLocaleTimeString() and
input with value based on your location. The clockType option is forced in that case.This option also allows to put object with properties which:
|
delayHandler | 300 | number | Set delay to clickable elements like button "OK", "CANCEL" etc. The value has to be set in milliseconds. |
Methods
Methods are custom function what can be used to manually change the behavior of timepicker.
HTML
<div class="timepicker-ui-test">
<input type="text" class="timepicker-ui-input" value="12:00 AM">
</div>
JavaScript
const timepicker = document.querySelector("timepicker-ui-test");
const init = new TimepickerUI(timepicker);
timepicker.create();
Table with methods
Name | Description | Parameters | Default | Parameters description |
---|---|---|---|---|
create | The create method init timepicker | - | - | - |
open | The open method opens immediately timepicker after init | (function) | undefined | The callback function is tiggered when timepicker is open by this method. Example: tmInstance.open(()=> console.log('triggered after open')); |
close | Closure method closes the timepicker | ()(boolean, function) | undefined | The first parentheses doesn't have any paremeters. The second parentheses accepts parameters and these parameters are optional in this method and order is any. You can set callback function first or boolean, or just boolean or just callback. If the boolean is set to true the input will be updating with the current value on picker. The callback function start immediately after close, if is invoke. The max parameters length are set to 2
Examples: tmInstance.close()(() => console.log('triggered after close')); tmInstance.close()(true, () => console.log('triggered after close')); tmInstance.close()(true); |
update | The update method | (object, function) | ({ options: {}, create: boolean }, callback) | The first parameter is a object with key options which is timepicker options and it will be updated to current instance and is `required` The `create` key wchich if is set to true is starting the create() method after invoke update function and is optional. The `create` option is useful if you are using destroy and update methods together. The callback function is triggered after update method is invoke and this parameter is optional.
Examples: tmInstance.update({options:{ amLabel:"test" }}, () => console.log('triggered after update')); tmInstance.update({options:{ amLabel:"test" }, create: true}, () => console.log('triggered after update')); tmInstance.update({options:{ amLabel:"test" }); |
destroy | The destroy method destroy actual instance of picker by cloning element. | (function) | undefined | The callback function is started after destroyed method. This parameter is optional.
Example: tmInstance.destroy(() => console.log('triggered after destroy')); |
Events
Events are custom events triggered when you add some event listeners to your timepicker element. If you want to have a property timepicker/input values you have to use detail
to the event object.
HTML
<div class="timepicker-ui-test">
<input type="text" class="timepicker-ui-input" value="12:00 AM">
</div>
JavaScript
const timepicker = document.querySelector("timepicker-ui-test");
const init = new TimepickerUI(timepicker);
timepicker.create();
timepicker.addEventListener("show", (event) => console.log(event.detail));
Table with events
Name | Description |
---|---|
show | The event starts if timepicker is showing up |
cancel | The event starts if timepicker is closing |
accept | The event starts if timepicker button OK is accepted |
update | The event starts if mouse/touch events are triggered on a clock face (multiple events) |
selectminutemode | The event starts if timepicker minute box is clicked |
selecthourmode | The event starts if timepicker hour box is clicked |
selectamtypemode | The event starts if timepicker am box is clicked |
selectpmtypemode | The event starts if timepicker pm box is clicked |
geterror | The event start if value in the input is wrong |
Future Plans
- keyboard accesibilty
- max/min time options
If you have more good ideas please let me know in issue. I will try to add more useful features. This project is still develop, if you find some bugs please report on the issue page.
License
MIT