Log In Sign Up
Home›Docs›Form›Datetime Library

Datetime Library

Category: Form
The Datetime module can create date picker instances, supporting single or multiple date selection, as well as date range selection. It also supports the use of lunar calendars and custom events.

Basic Usage

Apply the oc-datetime attribute to any node to create a date picker, though it's typically used on input, textarea, oc-input and oc-textarea nodes.

  • Output
  • HTML
  • 2024-02-06
  •

You can also create instances using the id+new approach.

  • Output
  • HTML
  • JS
  • 2024-02-06
  •                 
                
            
  •                 
                new orca.Datetime('#demo01');
                new orca.Datetime('#demo02');
                new orca.Datetime('#demo03');

Setting Initial Values

There are three ways to set initial values:

  1. Using the value parameter which supports multiple formats:

    • String dates, e.g.: 2024/02/06, 2024/02/06 12:3:24, 2024-02-06 (ISO format), and 05/06/2024, 05-06-2024, May 06,2024 (US format)
    • Object dates, e.g.: {YYYY:2024,MM:2,DD:12}
    • Date objects created by new Date()

  2. Directly assigning values to input elements using the value attribute - the plugin will automatically use this as the selected value

  3. Setting the fillNow parameter to true will automatically populate today's date as the selected value

Note: Priority is given to the value parameter. If value is empty, it will take values from input/div nodes. If those are also empty, it will use today's date.

  • Output
  • HTML

  • Value parameter passing

    Value attribute passing

    fillNow parameter passing

    Value attribute priority

    Value attribute priority

    Value parameter priority

  •

Supporting Multiple Date Formats

Initial values can accept various date text formats with high fault tolerance - even non-standard or incorrect date formats will be correctly parsed.

ISO Date Formats

  • 2024-05-12 (zero-padded), 2024-5-12 (unpadded), 2024-05-12 12:05:13 (zero-padded), 2024-5-12 12:5:13 (unpadded)
  • 2024-05-12T12:05:13 (zero-padded), 2024-5-12T12:5:13 (unpadded)
  • 2024-5-12 12:5:13Z, 2024-5-12 12:5:13+6:00 (unpadded), 2024-5-12T12:5:13Z, 2024-5-12T12:5:13+6:00 (unpadded),
  • 2024-05-12T12:5:13Z (valid zero-padded ISO date), 2024-05-12T12:5:13+06:00 (valid zero-padded ISO date)

The T character is used to replace the space between date and time to prevent errors during data transmission.

The Z and +- notations indicate UTC time, ensuring dates and times are correctly interpreted across computer systems regardless of timezone.

Z represents time with no timezone offset, +06:00 represents UTC+6, and -06:00 represents UTC-6.

  • Output
  • HTML
  •

Slash-Separated Date Formats

We often see dates using slashes / instead of hyphens - as separators. While not ISO standard, these will still be correctly parsed.

  • Output
  • HTML
  •

US/European Date Formats

Due to historical reasons, the US and Europe have their own traditional date formats. The following common formats will all be correctly parsed:

  • 8 12,2025
  • 8 12 2025
  • August 12,2025
  • Aug 12,2025
  • 12 August 2025
  • 12 Aug 2025

Both full month names and abbreviations are supported.

  • Output
  • HTML
  •

Timestamp Values

In addition to regular date text values, you can also use timestamps, but they must be in numeric format and passed via the value parameter.

  • Output
  • HTML
  •

Selection Modes

There are three selection modes that can be set via the mode parameter: single (single selection), multiple (multiple selection), and range (range selection). The default is single mode.

range mode will force display in a two-column panel layout.

  • Output
  • HTML

  • Single selection

    Multiple selection

    Range selection

  •

Multiple Panels

You can set the number of panels using the cols and rows parameters. Default is cols:1, rows:1 (single panel).

Note: If in range selection mode and cols:1, cols will be forced to 2.

The bottom button row will automatically adjust based on the number of columns - when cols is 1, buttons appear in a linear layout; when cols>1, buttons use a left-right layout.

For non-inline display modes, it's recommended to keep rows<=2 to avoid scrollbars.

  • Output
  • HTML

  • Two columns in one row

    Three columns in two rows

  •

Common Formats

Set output text format using the format parameter, supporting the following keywords:

  • BC: BC era expression text
  • AD: AD era expression text
  • YYYY: Year (unpadded)
  • M: Month (unpadded); MM: Zero-padded month; MMM: Month abbreviation; MMMM: Full month name
  • D: Day (unpadded); DD: Zero-padded day
  • d: Week index (Sunday=0); dd: Minimal weekday name (2 chars); ddd: Weekday abbreviation (3 chars); dddd: Full weekday name
  • H: Hour (24-hour, unpadded); HH: Zero-padded hour (24-hour)
  • h: Hour (12-hour, unpadded); hh: Zero-padded hour (12-hour)
  • A: AM/PM indicator (uppercase)
  • a: am/pm indicator (lowercase)
  • m: Minute (unpadded); mm: Zero-padded minute
  • s: Second (unpadded); ss: Zero-padded second
  • SSS: Three-digit milliseconds
  • W: Week of year (index); WW: Zero-padded week index
  • w: Week of month (index); ww: Zero-padded week index

Common format parameter combinations:

  • YYYY - Enables year type main panel
  • YYYY-M, YYYY/M, YYYY-MM, YYYY/MM - Enables month type main panel
  • YYYY-M-D, YYYY/M/D, YYYY-MM-DD, YYYY/MM/DD - Enables date type main panel
  • YYYY-M-D H, YYYY/M/D H, YYYY-MM-DD HH, YYYY/MM/DD HH - Enables date main panel with daytime selection sub-panel
  • YYYY-MM-DD HH:mm or YYYY/MM/DD HH:mm - Enables date main panel with daytime sub-panel
  • YYYY-M-D H:m:s, YYYY/M/D H:m:s, YYYY-MM-DD HH:mm:ss, YYYY/MM/DD HH:mm:ss - Enables date main panel with daytime sub-panel
  • H:m:s and HH:mm:ss - No main panel, only daytime selection sub-panel
  • H:m and HH:mm - No main panel, only daytime selection sub-panel
  • H and HH - No main panel, only daytime selection sub-panel

For BC years, use the BC keyword. To customize the "BC" text, use the lang.BC parameter.

  • Output
  • HTML
  •

When dealing with years less than 100 or BC dates, using traditional Western date formats may cause parsing issues. It's not recommended to use formats like "MM DD, YYYY BC" in these cases.

UTC Format

In computer systems, UTC format is commonly used to store date data to prevent transmission errors. It has three distinct characteristics:

  1. Must include year, month, day, hour, minute and second
  2. If using T between date and time, the date separators must be hyphens - with zero-padding. Space separators have no restrictions
  3. Time must be followed by timezone indicator Z, + or -
  • Output
  • HTML
  •

Range Values

In range selection mode, besides the common date ranges, you can also configure range months, range years and range times using the format parameter.

  • Output
  • HTML
  •

Display Modes

Use the display parameter to set how the date window appears:

  • inline - Displays below the input or div
  • popup - Displays as positioned bubble (default)
  • dialog - Displays as centered dialog
  • drawer - Displays as bottom drawer
  • Output
  • HTML

  • inline

    popup

    dialog

    drawer

  •

When opening the Datetime module as a dialog, you can add a heading parameter to make the dialog draggable.

Additional bubble parameters can be added via the bubble parameter.

  • Output
  • HTML
  •

Flexible Layout

The date picker defaults to a fixed width to match standard input elements. For inline display mode where you need it to fill the container, set the full parameter to true to make the date picker take 100% width.

  • Output
  • HTML
  •

Auto-Fill

By default, clicking date cells saves the selected value internally but doesn't assign it to the input until clicking "Confirm". Set autoFill to true to automatically merge and fill the time into the input when clicking date cells. Clicking time cells will also automatically update the input value.

  • Output
  • HTML
  •

Required Selection

By default, no selection outputs an empty value. Set required to true to force at least one selection.

  • Output
  • HTML
  •

Disabled State

Set disabled:true to disable the instance.

  • Output
  • HTML
  •

Basic Configuration Parameters

Property Type Default Description
name string '' Target node's name attribute
value string/Date '' Date value, supports multiple formats like 2022-2-3, 2022/2/3 or Date objects
disabled boolean false Whether disabled
size 'sm'/'md'/'lg'/'' '' Target node size
format string '' Date format like YYYY-MM-DD, YYYY/MM/DD HH:mm:ss etc
classes string '' Custom CSS classes for date window

Display Mode Parameters

Property Type Default Description
mode 'single'/'multiple'/'range' 'single' Selection mode: single/multiple/range
feature 'single'/'static' 'single' Special feature combination type
display 'popup'/'inline'/'dialog'/'drawer' 'popup' Display mode
toDrawer boolean true Whether to switch to drawer mode on mobile
full boolean false Whether to take 100% container width

Display Mode Parameters

Property Type Default Description
mode 'single'/'multiple'/'range' 'single' Selection mode: single/multiple/range
feature 'single'/'static' 'single' Special feature combination type
display 'popup'/'inline'/'dialog'/'drawer' 'popup' Display mode
toDrawer boolean true Whether to switch to drawer mode on mobile
full boolean false Whether to take 100% container width

Date Restriction Parameters

Property Type Default Description
maxSelection number 100 Maximum number of selections (in multiple selection mode)
minDate string/Date '' Minimum selectable date
maxDate string/Date '' Maximum selectable date
datespan array [] Valid date range (year/month/day)
timespan array [] Valid time range

Layout Parameters

Property Type Default Description
rows number 1 Number of panel rows
cols number 1 Number of panel columns
weekStart 'ISO'/'USA' 'ISO' First day of week - ISO defaults to Monday, USA to Sunday
headFormat 'ISO'/'USA' 'ISO' Panel header layout - ISO shows 'YYYY+M', USA shows 'MMM+YYYY'
separator string ',' Separator for multiple dates

Button Control Parameters

Property Type Default Description
nowHide boolean false Whether clicking "Now" button closes window
nowShow boolean false Whether to show "Now" button
clearShow boolean true Whether to show "Clear" button
closeShow boolean true Whether to show "Close" button
cancelShow boolean false Whether to show "Cancel" button
confirmHide boolean true Whether clicking confirm button closes window

Automation Behavior Parameters

Property Type Default Description
autoFill boolean false Whether to auto-fill selected values
manual boolean false Whether to allow manual input
autoCorrect boolean true Whether to auto-correct current value
required boolean false Whether at least one date must be selected
fillNow boolean false Whether to auto-fill today's date when empty

Selector Parameters

Property Type Default Description
btnSel string '' Trigger button selector
posSel string '' Positioning node selector
inputSel string '' Input/output node selector
childSel string '' Child node selector

Extension Parameters

Property Type Default Description
lunar object {enable: false, ...} Lunar calendar configuration
events object {enable: false, ...} Event indicator configuration
menu array [] Left tool panel configuration
bubble object {} Popup parameters configuration
footer object {enable: true, layout: 'plain', children: ['clear', 'confirm']} Bottom button configuration

Pre-Callback Functions

Property Type Default Description
b4fill function null Before value fill callback
b4Remove function null Before item removal callback
b4Set function null Before item selection callback
b4Clear function null Before clear callback
b4Cancel function null Before cancel callback
b4Confirm function null Before confirm callback

Callback Functions

Property Type Default Description
onFilled function null After value filled callback
onRemoved function null After item removed callback
onSet function null After item selected callback
onSetRange function null After date range set callback
onCreatedPanels function null After panels created callback
onCanceled function null After canceled callback
onConfirmed function null After confirmed callback
onCleared function null After cleared callback
onOpened function null After opened callback
onClosed function null After closed callback
onTransferred function null After node transferred callback
onUpdatedTime function null After time updated callback

Prev
Textarea Component: More Display Variants, Validation, Event, and Method Usage Examples
4 months ago

New Launch: 20% Off All Products

Unlock all examples and development resources