Element: <oj-c-date-picker>

CORE PACK

Oracle® JavaScript Extension Toolkit (JET)
17.1.0
G12196-01

Since:
  • 17.0.0
Module:
  • date-picker

Note: This component supersedes the following component: <oj-date-picker>. Migration info available at preceding link.

QuickNav

Attributes

Methods

Type Definitions

Other Topics


JET DatePicker Component

Description: A DatePicker is a calendar interface that allows users to select a single date.

<oj-c-date-picker value="2023-03-20"></oj-c-date-picker>

Touch End User Information

Target Gesture Action
Month/Year picker buttons Tap Toggles between Date picker mode and Month/Year picker mode.
Prev/Next buttons Tap Moves to the prev/next month in the date picker or to the prev/next decade in the year picker.
Today button Tap Navigates to the Year and Month that contains today's date.
Day Button Tap Selects this day as the current date.
Month Button Tap In the month picker, selects this month and returns to the date picker, refreshing the display to show the selected month.
Year Button Tap In the year picker, selects this year and returns to the date picker, refreshing the display to show the selected year.

Keyboard End User Information

Target Key Action
Date Picker Tab Moves the focus to next element in the date picker sequence. Only one element in the calendar grid is in the Tab sequence (current day/month/year or selected day/month/year depending on scenario). If focus is on the last tabbable element inside the date picker, moves focus off the date picker to the next tabbable element on the page.
Date Picker Shift + Tab Moves the focus to the previous tabbable element inside the date picker. If focus is on the first tabbable element inside the date picker, moves focus off the date picker to the previous tabbable element on the page.
Date Picker Enter/Space Selects the currently focused day or activates the button currently focused.
Calendar Grid PageUp Changes the calendar grid to the previous month. Moves focus to the closest day in the previous month.
Calendar Grid PageDown Changes the calendar grid to the next month. Moves focus to the closest day in the next month.
Calendar Grid Shift + PageUp Changes the calendar grid to the previous year. Moves focus to the closest day of the same month in the previous year.
Calendar Grid Shift + PageDown Changes the calendar grid to the next year. Moves focus to the closest day of the same month in the next year.
Calendar Grid Ctrl + Alt + T or Ctrl + Option + T Changes the calendar grid to the year and month that contains today's date. Moves focus to Today.
Calendar Grid Home Go to the first day of the current month.
Calendar Grid End Go to the last day of the current month.
Calendar Grid ArrowLeft Moves focus to the previous day. In RTL, this will move focus to the next day.
Calendar Grid ArrowRight Moves focus to the next day. In RTL, this will move focus to the previous day.
Calendar Grid ArrowUp Moves focus to the same day of the previous week.
Calendar Grid ArrowDown Moves focus to the same day of the next week.
Months Grid Enter/Space Selects the currently focused month and returns to the date picker, refreshing the display to show the selected month.
Months Grid UpArrow Moves focus to four months back from the current focused month.
Months Grid DownArrow Moves focus to four months ahead from the current focused month.
Months Grid RightArrow Moves focus to the next month. In RTL, this will move focus to the previous month.
Months Grid LeftArrow Moves focus to the previous month. In RTL, this will move focus to the next month.
Years Grid Enter/Space Selects the currently focused year and returns to the date picker, refreshing the display to show the selected month.
Years Grid PageUp Changes the year grid to the previous decade. The focus remains in the same location with respect to the current decade.
Years Grid PageDown Changes the year grid to the next decade. The focus remains in the same location with respect to the current decade.
Years Grid UpArrow Moves focus to four years back from the current focused year. If that year is not in the year grid, go back 1 decade.
Years Grid DownArrow Moves focus to four years ahead from the current focused year. If that year is not in the year grid, go ahead 1 decade.
Years Grid RightArrow Moves focus to the next year. In RTL, this will move focus to the previous year.
Years Grid LeftArrow Moves focus to the previous year. In RTL, this will move focus to the next year.

Accessibility

The oj-c-date-picker is not intended to be a labelled component. Component authors using this component should use the aria-describedby to give a description of the date being entered.


Usage

Signature:

interface CDatePickerElement

Typescript Import Format
//To typecheck the element APIs, import as below.
import { CDatePickerElement } from "oj-c/date-picker";

//For the transpiled javascript to load the element's module, import as below
import "oj-c/date-picker";

For additional information visit:

Note: Application logic should not interact with the component's properties or invoke its methods until the BusyContext indicates that the component is ready for interaction.


Attributes

day-formatter :(date: Required<oj-c.DatePicker.CalendarDate>) => { state: "disabled" | "enabled" | "restricted"; }

A function that receives a date and returns an object specifying how to format the provided date. This function is called for each date that is rendered and this can be used to control how individual dates are rendered - disabled, restricted, or enabled.
Names
Item Name
Property dayFormatter
Property change event dayFormatterChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-day-formatter-changed

days-outside-month :"hidden"|"selectable"

The days-outside-month attribute affects the day cells that are outside of the current month.
Supported Values:
Value Description
hidden The days outside of the current month will be hidden.
selectable The days outside of the current month will be visible and selectable.
Default Value:
  • "hidden"
Names
Item Name
Property daysOutsideMonth
Property change event daysOutsideMonthChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-days-outside-month-changed

max :(string|null)

The maximum selectable date, in date only ISO string format. Dates in the date picker that are greater than this date will not be selectable. This must be a date only ISO string with no time, otherwise an error is thrown and the component will not render. When set to null, there is no maximum.
Default Value:
  • null
Names
Item Name
Property max
Property change event maxChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-max-changed

max-width :(number|string)

Specifies the component style maxWidth.

If not specified, defaults to the theme specified maxWidth.
This attribute accepts values of type:
0 | `${number}${CssUnits}` | `${number}x` | `--${string}` | `var($string})` | `${number}%`

When this component is used in composition and the component should take up 100% of the parent container's width, set maxWidth to '100%'.
Because there is a theme default value for maxWidth, when setting the width property to achieve a fixed width, set the maxWidth property to the same value.

Names
Item Name
Property maxWidth
Property change event maxWidthChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-max-width-changed

min :(string|null)

The minimum selectable date, in date only ISO string format. Dates in the date picker that are less than this date will not be selectable. This must be a date only ISO string with no time, otherwise an error is thrown and the component will not render. When set to null, there is no minimum.
Default Value:
  • null
Names
Item Name
Property min
Property change event minChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-min-changed

month-and-year-picker :"on"|"off"

The month-and-year-picker attribute can be used to specify whether or not the DatePicker should show the toggle buttons that toggle the month grid picker and year grid picker. The month picker grid allows the user to select a month to display in the date picker and the year picker grid allows the user to select the year to display in the date picker.
Supported Values:
Value Description
off The month and year toggle buttons will not be shown and the date picker renders the month and the year as text.
on The month and year toggle buttons will be shown.
Default Value:
  • "on"
Names
Item Name
Property monthAndYearPicker
Property change event monthAndYearPickerChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-month-and-year-picker-changed

readonly :boolean

Whether the component is readonly. When the component is readonly, the date picker can still be used to navigate to different calendar dates, but the date picker won't allow the date to be changed via user action.
Default Value:
  • false
Names
Item Name
Property readonly
Property change event readonlyChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-readonly-changed

today-button :"visible"|"hidden"

Specifies the visibility of the 'Go to today' button.
Supported Values:
Value Description
hidden The 'Go to Today' button will be hidden.
visible The 'Go to Today' button will be shown and it can be pressed to navigate to Today.
Default Value:
  • "visible"
Names
Item Name
Property todayButton
Property change event todayButtonChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-today-button-changed

today-time-zone :string

The today-time-zone attribute is used to compute today's date. This defaults to the user's system timezone.

The only reason an application would set the today-time-zone property is if they want the highlighted today cell to be in a different timezone than the user's system's timezone, like if the user has a preferred timezone that is not where they are physically working.

Names
Item Name
Property todayTimeZone
Property change event todayTimeZoneChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-today-time-zone-changed

value :(string|null)

The value of the component.

The value must be a local date (no time) ISO string such as '2021-03-14', otherwise the component will throw an error.

The oj-c-date-picker initially opens to the selected date if there is one and it is within the min/max range. If there is no value, the DatePicker initially opens to today's month.

Default Value:
  • null
Supports writeback:
  • true
Names
Item Name
Property value
Property change event valueChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-value-changed

week-display :"none"|"number"

Whether week of the year will be shown in the DatePicker. The default calculation follows the rule for ISO 8601 as follows: The first week of the year is defined as the week that contains the first Thursday. Therefore, if January 1st falls on a Friday, it is considered part of the last week of the previous year. Conversely, if December 31st falls on a Wednesday, it is part of week 1 of the following year.
Supported Values:
Value Description
none The week of the year column will not be shown.
number Will show the week of the year as a number.
Default Value:
  • "none"
Names
Item Name
Property weekDisplay
Property change event weekDisplayChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-week-display-changed

width :(number|string)

Specifies the component style width.

If not specified, defaults to '100%'.

This attribute accepts values of type:

0 | `${number}${CssUnits}` | `${number}x` | `--${string}` | `var($string})` | `${number}%`


Because there is a theme default value for maxWidth, when setting the width property to achieve a fixed width, set the maxWidth property to the same value.

Names
Item Name
Property width
Property change event widthChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-width-changed

Methods

getProperty(property) : {any}

Retrieves the value of a property or a subproperty.
Parameters:
Name Type Description
property The property name to get. Supports dot notation for subproperty access.
Returns:
Type
any

setProperties(properties) : {void}

Performs a batch set of properties.
Parameters:
Name Type Description
properties An object containing the property and value pairs to set.
Returns:
Type
void

setProperty(property, value) : {void}

Sets a property or a single subproperty for complex properties and notifies the component of the change, triggering a corresponding event.
Parameters:
Name Type Description
property The property name to set. Supports dot notation for subproperty access.
value The new value to set the property to.
Returns:
Type
void

Type Definitions

CalendarDate

Properties:
Name Type Argument
day number <optional>
month number <optional>
year number <optional>