Picker.js

JavaScript date time picker.

• Website

Table of contents

• 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'),
});

Or

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),
});

Or

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',
});

Or

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,
});

Or

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

MIT © Chen Fengyuan

⬆ Back to top