Convenient Calendar & Date Picker Component - tui.date-picker

Convenient Calendar & Date Picker Component - tui.date-picker
File Size: 165 KB
Views Total: 3624
Last Update:
Publish Date:
Official Website: Go to website
License: MIT
   

tui.date-picker is an easy-to-use, user-friendly, multi-language, highly customizable calendar, time/date/month/year picker and date range picker component implemented in jQuery or Vanilla JavaScript.

Features:

  • Calendar mode: inline calendar
  • Datepicker mode: time/date/month/year picker
  • DaterangePicker mode: allows you to select a date range.

Table Of Contents:

How to use it:

1. Install & download the tui.date-picker via NPM.

# NPM
$ npm install tui-date-picker --save

2. Import the tui.date-picker.

// ES 6
import DatePicker from 'tui-date-picker';

3. Or directly include the compiled & minified version of the the tui.date-picker component on the webpage. 

<!-- Vanilla JS Version (4.x) -->
<link href="/path/to/tui-date-picker.css" rel="stylesheet">
<script src="/path/to/tui-date-picker.js"></script>

<!-- jQuery Version (3.x) -->
<link href="/path/to/tui-date-picker.css" rel="stylesheet">
<script src="/path/to/jquery.min.js"></script>
<script src="/path/to/tui-code-snippet.min.js"></script>
<script src="/path/to/tui-date-picker.js"></script>

4. Include the tui.time-picker component in case you want to display a time picker inside the date picker.

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

5. Append the date picker to an input field.

<div class="tui-datepicker-input tui-datetime-input tui-has-focus">
  <input type="text" id="datepicker-input" aria-label="Date-Time">
  <span class="tui-ico-date"></span>
</div>
<div id="example"></div>
const myDatepicker = new tui.DatePicker('#example', {
      date: new Date(),
      input: {
        element: '#datepicker-input'
      }
});

6. Create an inline calendar using the createCalendar API.

<div id="calendar-example"></div>
var DatePicker = tui.DatePicker;
var myCalendar = DatePicker.createCalendar('#calendar-example',{
    // options here
});

7. Create a date range picker using the createRangePicker API.

<div class="tui-datepicker-input tui-datetime-input tui-has-focus">
  <input id="startpicker-input" type="text" aria-label="Date">
  <span class="tui-ico-date"></span>
  <div id="startpicker-container"></div>
</div>

<span>to</span>

<div class="tui-datepicker-input tui-datetime-input tui-has-focus">
  <input id="endpicker-input" type="text" aria-label="Date">
  <span class="tui-ico-date"></span>
  <div id="endpicker-container"></div>
</div>
var today = new Date();
var picker = tui.DatePicker.createRangePicker({
    startpicker: {
        date: today,
        input: '#startpicker-input',
        container: '#startpicker-container'
    },
    endpicker: {
        date: today,
        input: '#endpicker-input',
        container: '#endpicker-container'
    },
    selectableRanges: [
        [today, new Date(today.getFullYear() + 1, today.getMonth(), today.getDate())]
    ]
});

8. Possible options for the DatePicker API.

// options and defaults
const myDatepicker = new tui.DatePicker('#example', {

      // language
      language: 'en'

      // calendar options (see below)
      calendar: {},

      // element: input element
      // format: date format
      input: {
        element: null,
        format: null
      },

      // TUI TimePicker options
      timepicker: null,

      // initial date
      date: null,

      // always show the date picker
      showAlways: false,

      // 'date', 'month', 'year'
      type: 'date',

      // selectable date ranges
      selectableRanges: null,

      // opener button list
      openers: [],

      // auto close after selection
      autoClose: true,

      // send hostname to google analytics
      usageStatistics: true,

      // start of the week. 'Sun', 'Mon', ..., 'Sat'(default: 'Sun'(start on Sunday))
      weekStartDay: 'Sun'

});

9. Possible options for the Calendar API.

var myCalendar = DatePicker.createCalendar('#calendar-example',{

    // language
    language: 'en',

    // show today
    showToday: true,

    // show jump buttons
    showJumpButtons: false,

    // initial date
    date: new Date(),

    // 'date', 'month', 'year'
    type: 'date',

    // send hostname to google analytics
    usageStatistics: true,

    // 'Sun', 'Mon', ...
    weekStartDay: 'Mon',
    
});

10. Possible options for the DateRangePicker API.

var picker = tui.DatePicker.createRangePicker({

    // language
    language: 'en',

    // start date
    startpicker: {
      input: '#start-input',
      date: null,
      container: '#start-container',
      weekStartDay: 'Sun',
    },

    // end date
    endpicker: {
      input: '#end-input',
      date: null,
      container: '#end-container',
      weekStartDay: 'Sun',
    },

    // calendar options (see above)
    calendar: {},

    // TUI Timepicker options
    timepicker: null,

    // 'date' | 'month' | 'year'
    type: 'date',

    // date format
    format: 'yyyy-MM-dd'

    // selectable date ranges
    selectableRanges: [
      [new Date(2017, 3, 1), new Date(2017, 5, 1)],
      [new Date(2017, 6, 3), new Date(2017, 10, 5)]
    ],

    // always show the date picker
    showAlways: false,

    // auto close after selection
    autoClose: true,

    // send hostname to google analytics
    usageStatistics: true

});

11. Add your own languages.

DatePicker.localeTexts['myLang'] = {
  titles: {
    // days
    DD: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'],
    // daysShort
    D: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
    // months
    MMMM: [
      'January', 'February', 'March', 'April', 'May', 'June',
      'July', 'August', 'September', 'October', 'November', 'December'
    ],
    // monthsShort
    MMM: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
  },
  titleFormat: 'MMM yyyy',
  todayFormat: 'D, MMMM dd, yyyy',
  date: 'Date',
  time: 'Time'
};

const datepicker = new DatePicker('#datepicker-container', {
  language: 'myLang'
});

12. API methods.

/* Datepicker Methods */

// Add CSS class
myDatepicker.addCssClass(className);

// Add an opener (trigger element)
myDatepicker.addOpener(opener);

// Add a selectable range
myDatepicker.addRange(start, end);

// Change language
myDatepicker.changeLanguage(language);

// Open the date picker
myDatepicker.open();

// Close
myDatepicker.close();

// Enable
myDatepicker.enable();

// Disable
myDatepicker.disable();

// Toggle the date picker
myDatepicker.toggle();

// Destroy
myDatepicker.destroy();

// year -> month -> dat
myDatepicker.drawLowerCalendar(date);

// date -> month -> year
myDatepicker.drawUpperCalendar(date);

// Return the first overlapped range from the point or range
myDatepicker.findOverlappedRange(startDate, endDate);

// Return the calendar instance.
myDatepicker.getCalendar();

// Return the current calendar type
myDatepicker.getCalendarType();

// Return the selected date
myDatepicker.getDate();

// Return the date elements on the calendar
myDatepicker.getDateElements();

// Return the locale text object
myDatepicker.getLocaleText();

// Return the time picker instance
myDatepicker.getTimePicker();

// Return the date picker's type
// 'date''month''year'
myDatepicker.getType();

// Check whether the date picker is disabled
myDatepicker.isDisabled();

// Check whether the date picker is opened
myDatepicker.isOpened();

// Check whether the date picker is selectable
myDatepicker.isSelectable(date);

// Check whether the date is selected
myDatepicker.isSelected(date);

// Remove all openers
myDatepicker.removeAllOpeners();

// Remove a CSS class from the date picker
myDatepicker.removeCssClass(className);

// Remove an opener
myDatepicker.removeOpener(opener);

// Remove a range. Use Date instances or numbers(timestamp).
myDatepicker.removeRange(start, end, type);

// Select a date
myDatepicker.setDate(date);

// Set date format
myDatepicker.setDateFormat(format);

// Set the input element
myDatepicker.setInput(element, options);

// Set no date to be selected
myDatepicker.setNull();

// Set selectable ranges
myDatepicker.setRanges(ranges);

// Set the calendar's type
myDatepicker.setType(type);

/* Calendar Methods */

// Add CSS class
myCalendar.addCssClass(className);

// Change language
myCalendar.changeLanguage(language);

// Hide the calendar
myCalendar.hide();

// Destroy
myCalendar.destroy();

// Draw the calendar
myCalendar.draw(options);

// Draw the next page.
myCalendar.drawNext();

// Draw the prev page.
myCalendar.drawPrev();

// Return the rendered date.
myCalendar.getDate();

// Return the date elements on the calendar
myCalendar.getDateElements();

// Return the date picker's type
// 'date''month''year'
myCalendar.getType();

// Return the next date
myCalendar.getNextDate();

// Get the date one year later
myCalendar.getNextYearDate();

// Return the previous date
myCalendar.getPrevDate();

// Get the date one year ago
myCalendar.getPrevYearDate();

/* Date Range Picker Methods */

// Add a selectable range
myRangePicker.addRange(start, end);

// Change language
myRangePicker.changeLanguage(language);

// Destroy
myRangePicker.destroy();

// Return the end date
myRangePicker.getEndDate();

// Return the end-datepicker
myRangePicker.getEndpicker();

// Return the start date
myRangePicker.getStartDate();

// Return the start-datepicker
myRangePicker.getStartpicker();

// Remove a range. 
myRangePicker.removeRange(start, end, type);

13. Events.

/* Datepicker Events */

myDatepicker.on('change', () => {
  // do something
});

myDatepicker.on('close', () => {
  // do something
});

myDatepicker.on('draw', (e) => {
  // e.date
  // e.type
  // e.dateElements
});

myDatepicker.on('open', () => {
  // do something
});

/* Calendar Events */

myCalendar.on('draw', (e) => {
  // e.date
  // e.type
  // e.dateElements
});

/* Date Range Picker Events */

myCalendar.on('change:end', () => {
  // do something
});

myCalendar.on('change:start', () => {
  // do something
});

Changelog:

v4.3.1 (09/30/2021)

  • Bug Fixes

v4.3.0 (09/05/2021)

  • Feat: set date to today by click today text

v4.2.2 (07/08/2021)

  • Bug Fixes

v4.2.0 (03/18/2021)

  • Feat: add option to start on monday

This awesome jQuery plugin is developed by nhnent. For more Advanced Usages, please check the demo page or visit the official website.