Picker.js

JavaScript date time picker.

Website

Main
Getting started
Options
Methods
Events
No conflict
Browser support
Versioning
License

Main

dist/
├── picker.css
├── picker.min.css   (compressed)
├── picker.js        (UMD)
├── picker.min.js    (UMD, compressed)
├── picker.common.js (CommonJS, default)
└── picker.esm.js    (ES Module)

Getting started

Installation

npm install pickerjs

Include files:

<link  href="/path/to/picker.css" rel="stylesheet">
<script src="/path/to/picker.js"></script>

Usage

Syntax

new Picker(element[, options])

element
- Type: HTMLElement
- The target element for picking.
options (optional)
- Type: Object
- The options for picking. Check out the available options.

Example

<input type="text" id="input">

var input = document.getElementById('input');
var picker = new Picker(input, {
  format: 'YYYY/MM/DD HH:mm',
});

⬆ Back to top

Options

You may set picker options with new Picker(element, options). If you want to change the global default options, You may use Picker.setDefaults(options).

container

Type: Element or Selector
Default: null

Define the container for putting the picker. If not present, the picker will be appended to the document.body.

new Picker(element, {
  container: document.querySelector('.picker-container'),
});

new Picker(element, {
  container: '.picker-container',
});

controls

Type: Boolean
Default: false

Indicate whether show the prev and next arrow controls on each column.

date

Type: Date or String
Default: null

The initial date. If not present, use the current date.

new Picker(element, {
  date: new Date(2048, 9, 24, 5, 12),
});

new Picker(element, {
  date: '2048-10-24 05:12',
});

format

Type: String
Default: 'YYYY-MM-DD HH:mm'
Tokens:
- YYYY: 4 digits year with leading zero
- YYY: 3 digits year with leading zero
- YY: 2 digits year with leading zero and be converted to a year near 2000
- Y: Years with any number of digits and sign
- MMMM: Month name
- MMM: Short month name
- MM: Month number with leading zero
- M: Month number
- DD: Day of month with leading zero
- D: Day of month
- HH: Hours with leading zero
- H: Hours
- mm: Minutes with leading zero
- m: Minutes
- ss: Seconds with leading zero
- s: Seconds
- SSS: Milliseconds with leading zero
- SS: Milliseconds with leading zero
- S: Milliseconds

The date string format, also as the sorting order of date time columns.

new Picker(element, {
  date: '2048-10-24 05:12:02.056',
  format: 'YYYY-MM-DD HH:mm:ss.SSS',
});

new Picker(element, {
  date: 'Oct 24, 2048',
  format: 'MMM D, YYYY',
});

headers

Type: Boolean
Default: false

Indicate whether show the column headers. The text content of each header is defined in the text option.

increment

Type: Number or Object
Default: 1

Define the increment for each date time part.

new Picker(element, {
  increment: 10,
});

new Picker(element, {
  increment: {
    year: 1,
    month: 1,
    day: 1,
    hour: 1,
    minute: 10,
    second: 10,
    millisecond: 100,
  },
});

inline

Type: Boolean
Default: false

Enable inline mode.

language

Type: String (ISO language code)
Default: ''

Define the language.

You should define the language first. Check out the i18n folder for more information.

months

Type: Array
Default: ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']

Months' name.

monthsShort

Type: Array
Default: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']

Short months' name.

rows

Type: Number
Default: 5

Define the number of rows for showing.

text

Type: Object

Default:

{
  title: 'Pick a date and time',
  cancel: 'Cancel',
  confirm: 'OK',
  year: 'Year',
  month: 'Month',
  day: 'Day',
  hour: 'Hour',
  minute: 'Minute',
  second: 'Second',
  millisecond: 'Millisecond',
}

Define the title and button text of the picker.

translate

Type: Function

Default:

function (type, text) {
  return text;
}

Translate date time text.

new Picker(element, {
  translate(type, text) {
    const aliases = ['〇', '一', '二', '三', '四', '五', '六', '七', '八', '九'];

    return String(text).split('').map((n) => aliases[Number(n)]).join('');
  },
});

show

Type: Function
Default: null

The shortcut of the show event.

shown

Type: Function
Default: null

The shortcut of the shown event.

hide

Type: Function
Default: null

The shortcut of the hide event.

hidden

Type: Function
Default: null

The shortcut of the hidden event.

pick

Type: Function
Default: null

The shortcut of the pick event.

⬆ Back to top

Methods

If a method doesn't need to return any value, it will return the picker instance (this) for chain composition.

show()

Show the picker.

hide()

Hide the picker.

prev(type)

type:
- Type: String
- Options: 'year', 'month', 'day', 'hour', 'minute', 'second', 'millisecond'
- Date time type.

Pick the previous item.

next(type)

type: (the same as the prev method)

Pick the next item.

pick()

Pick the current date to the target element.

getDate([formatted])

formatted (optional):
- Type: Boolean
- Format the date.
(return value):
- Type: Date or String

Get the current date.

const picker = new Picker(element, {
  date: new Date(2048, 9, 24, 5, 12),
});

picker.getDate();
// > Sat Oct 24 2048 05:12:00 GMT+0800 (China Standard Time)

picker.getDate(true);
// > 2048-10-24 05:12

setDate(date)

date:
- Type: Date
- The new date.

Override the current date with a new date.

update()

Update the picker with the current the element value / text.

reset()

Reset the picker and the element value / text.

parseDate(date)

date:
- Type: String
(return value):
- Type: Date

Parse a date string with the set date format.

const picker = new Picker(element, options);

picker.parseDate('2048-10-24 05:12');
// > Sat Oct 24 2048 05:12:00 GMT+0800 (China Standard Time)

formatDate(date)

date:
- Type: Date
(return value):
- Type: String
- The formatted date string.

Format a date object to a string with the set date format.

const picker = new Picker(element, options);

picker.formatDate(new Date(2048, 9, 24, 5, 12));
// > 2048-10-24 05:12

destroy()

Destroy the picker and remove the instance from the target element.

⬆ Back to top

Events

show

This event fires when a picker modal starts to show.

Only available in non-inline mode.

shown

This event fires when a picker modal has shown.

Only available in non-inline mode.

hide

This event fires when a picker modal starts to hide.

Only available in non-inline mode.

hidden

This event fires when a picker modal has hidden.

Only available in non-inline mode.

pick

This event fires when pick the current date to the target element.

If the target element is an <input> or <textarea> element, then a change event will be triggered too.

⬆ Back to top

No conflict

If you have to use other picker with the same namespace, just call the Picker.noConflict static method to revert to it.

<script src="other-picker.js"></script>
<script src="picker.js"></script>
<script>
  Picker.noConflict();
  // Code that uses other `Picker` can follow here.
</script>

Browser support

Chrome (latest)
Firefox (latest)
Safari (latest)
Opera (latest)
Edge (latest)
Internet Explorer 9+

Versioning

Maintained under the Semantic Versioning guidelines.

License

⬆ Back to top

TomSinclair/pickerjs

Picker.js

Table of contents

Main

Getting started

Installation

Usage

Syntax

Example

Options

container

controls

date

format

headers

increment

inline

language

months

monthsShort

rows

text

translate

show

shown

hide

hidden

pick

Methods

show()

hide()

prev(type)

next(type)

pick()

getDate([formatted])

setDate(date)

update()

reset()

parseDate(date)

formatDate(date)

destroy()

Events

show

shown

hide

hidden

pick

No conflict

Browser support

Versioning

License