Current Version: 4.0.10

Note:

Any Coral CSS classes and attributes not explicitly mentioned in the public documentation are private and subject to change. Their direct use is not recommended and at high risk of breaking after subsequent updates of CoralUI library. For technical details of how to use Coral safely, please refer to the CoralUI Architecture.

Github: @coralui/coralui-component-datepicker

The Datepicker component provides desktop and touch friendly for both date and time selection. The component leverages moment.js for parsing, manipulating, and formatting dates.

Forms

Vertical Layout

Show Markup

<form class="coral-Form coral-Form--vertical u-columnMedium">
  <section class="coral-Form-fieldset">
    <div class="coral-Form-fieldwrapper">
      <label id="label-vertical-0" class="coral-Form-fieldlabel">Label</label>
      <coral-datepicker class="coral-Form-field" placeholder="Choose a date" name="name" labelledby="label-vertical-0"></coral-datepicker>
    </div>
  
    <div class="coral-Form-fieldwrapper">
      <label id="label-vertical-1" class="coral-Form-fieldlabel">Required</label>
      <coral-datepicker class="coral-Form-field" placeholder="Choose a date" name="name" labelledby="label-vertical-1" required></coral-datepicker>
      <coral-icon class="coral-Form-fieldinfo" icon="infoCircle" size="S" id="coral-form-vertical-datepicker-fieldinfo"></coral-icon>
      <coral-tooltip variant="info" placement="right" target="#coral-form-vertical-datepicker-fieldinfo">Required Information</coral-tooltip>
    </div>
  
    <div class="coral-Form-fieldwrapper">
      <label id="label-vertical-2" class="coral-Form-fieldlabel">Invalid</label>
      <coral-datepicker class="coral-Form-field" placeholder="Choose a date" name="name" labelledby="label-vertical-2" invalid></coral-datepicker>
      <coral-icon class="coral-Form-fielderror" icon="infoCircle" size="S" id="coral-form-vertical-datepicker-fielderror"></coral-icon>
      <coral-tooltip variant="error" placement="right" target="#coral-form-vertical-datepicker-fielderror">Error Message</coral-tooltip>
    </div>
  </section>
</form>

Aligned Layout

Show Markup

<form class="coral-Form coral-Form--aligned u-columnLarge">
  <section class="coral-Form-fieldset">
    <div class="coral-Form-fieldwrapper">
      <label id="label-aligned-0" class="coral-Form-fieldlabel">Label</label>
      <coral-datepicker class="coral-Form-field" placeholder="Choose a date" name="name" labelledby="label-aligned-0"></coral-datepicker>
    </div>
  
    <div class="coral-Form-fieldwrapper">
      <label id="label-aligned-1" class="coral-Form-fieldlabel">Required</label>
      <coral-datepicker class="coral-Form-field" placeholder="Choose a date" name="name" labelledby="label-aligned-1" required></coral-datepicker>
      <coral-icon class="coral-Form-fieldinfo" icon="infoCircle" size="S" id="coral-form-aligned-datepicker-fieldinfo"></coral-icon>
      <coral-tooltip variant="info" placement="right" target="#coral-form-aligned-datepicker-fieldinfo">Required Information</coral-tooltip>
    </div>
  
    <div class="coral-Form-fieldwrapper">
      <label id="label-aligned-2" class="coral-Form-fieldlabel">Invalid</label>
      <coral-datepicker class="coral-Form-field" placeholder="Choose a date" name="name" labelledby="label-aligned-2" invalid></coral-datepicker>
      <coral-icon class="coral-Form-fielderror" icon="infoCircle" size="S" id="coral-form-aligned-datepicker-fielderror"></coral-icon>
      <coral-tooltip variant="error" placement="right" target="#coral-form-aligned-datepicker-fielderror">Error Message</coral-tooltip>
    </div>
  </section>
</form>

JavaScript Examples

The following examples demonstrate usage of the JavaScript API's for Coral.Datepicker.

The following JavaScript manually initializes the component on page initialization and adds it to the DOM.

<script>
$(document).ready(function() {
  var datepicker = new Coral.Datepicker().set({
    id: 'myDatepicker',
    min: '2015-06-27T00:00+02:00',
    max: '2015-08-27T00:00+02:00',
    valueAsDate: new Date(2015,6,27)
  });
  document.getElementById('constructorExample').appendChild(datepicker);
})
</script>
<coral-datepicker class="coral-InputGroup" type="date" role="datepicker" id="myDatepicker"><input type="hidden" handle="hiddenInput" value="2015-07-27">
<input is="coral-textfield" class="coral3-Textfield coral-InputGroup-input" type="text" handle="input" role="textbox">
<div class=" coral-InputGroup-button" handle="toggleButtonContainer">
<button is="coral-button" class="coral3-Button coral3-Button--secondary" size="M" variant="secondary" type="button" icon="calendar" iconsize="S" handle="toggle" aria-haspopup="true" aria-label="Calendar" title="Calendar"><coral-icon class="coral3-Icon" icon="calendar" size="S"></coral-icon><coral-button-label></coral-button-label></button>
</div>
<coral-popover class="coral3-Popover" aria-hidden="true" tabindex="0" closable="off" role="dialog" aria-live="assertive" handle="popover" id="coral-id-0" alignmy="right top" alignat="right bottom" collision="fit"><div coral-tabcapture="top" tabindex="0"></div><div class="coral3-Dialog-header coral3-Popover-header" hidden=""><coral-icon class="coral3-Icon coral3-Dialog-typeIcon" icon="" size="S" handle="icon"></coral-icon>
<div handle="headerContent" class=" coral3-Dialog-title coral-Heading coral-Heading--2"><coral-popover-header></coral-popover-header></div>
<button is="coral-button" class="coral3-Button coral3-Dialog-closeButton coral3-Button--minimal" size="M" variant="minimal" handle="closeButton" type="button" icon="close" iconsize="XS" title="Close" tabindex="-1" coral-close=""><coral-icon class="coral3-Icon" icon="close" size="XS"></coral-icon><coral-button-label></coral-button-label></button></div><div class="coral3-Popover-content"><coral-popover-content></coral-popover-content></div><div coral-tabcapture="intermediate" tabindex="0"></div><div coral-tabcapture="bottom" tabindex="0"></div></coral-popover></coral-datepicker>

Getting the value

The following will display the above component's value in an alert.

<script>
function displayValue() {
  var value = document.querySelector('#myDatepicker').value;
  alert('The value is ' + value + '.');
}
</script>

Setting the value

The following will set the above component's value to July 26th 2015.

<script>
  function setValue() {
    var datepicker = document.querySelector('#myDatepicker');
    datepicker.valueAsDate = new Date(2015,06,26);
  }
</script>

Responding to user interaction

The following example shows how to detect changes performed by the user.

<script>
  $(document).ready(function () {
    var eventLog = $('#datepickerLog');
    document.querySelector('#myDatepicker').on('change', function(event) {
      var value = event.target.value;
      eventLog.log('Datepicker new value: ' + value);
    });
  });
</script>

Working with locales

The following example sets up the component to use the appropriate date formatting for the specified page locale (e.g. <html lang="fr-FR">). Requires moment-with-locales.js.

<script>
$(document).ready(function() {
  moment.locale(document.documentElement.lang || window.navigator.language || 'en');
  var datepicker = new Coral.Datepicker().set({
    id: 'myDatepicker',
    min: '2015-06-27T00:00+02:00',
    max: '2015-08-27T00:00+02:00',
    valueAsDate: new Date(2015,6,27),
    displayFormat: moment().format('L'),
    startDay : moment.localeData().firstDayOfWeek()
  });
})
</script>

Note: moment-with-locales.js provides support to close to 100 locales. If maintaining minimal footprint is critical to your product, it's possible to generate a custom version (moment-with-locales.custom.js) that limits support to a set of languages you can specify.

Log

Coral.Datepicker API

Constructor

JavaScript:: new Coral.Datepicker() or document.createElement('coral-datepicker')
HTML Tag:: <coral-datepicker>

Extends

Static Properties

Coral.Datepicker.type {String}

Datepicker types.

Properties:

Name	Type	Value	Description
DATE	String	date	The selection overlay contains only a calendar.
DATETIME	String	datetime	Provides both calendar and time controls in the selection overlay.
TIME	String	time	The selection overlay provides only time controls

Coral.Datepicker.variant {String}

Enum for Datepicker variant values.

Properties:

Name	Type	Value	Description
DEFAULT	String	default	A default, gray Datepicker.
QUIET	String	quiet	A Datepicker with no border or background.

Instance Properties

instance.disabled {Boolean} Reflected

Whether this field is disabled or not.

Inherited From:

Coral.mixin.formField#disabled

Default Value:

false

HTML Attribute:

disabled

instance.displayFormat {String}

The format used to display the selected date(time) to the user. If the user manually types a date, this format will be used to parse the value. When using this component on a mobile device, the display format must follow the format used by the native input. The default value depends on the type, which can be one from YYYY-MM-DD, YYYY-MM-DD[T]HH:mmZ or HH:mm. If an empty string is provided, then the default value per type will be used. See http://momentjs.com/docs/#/displaying/ for valid format string options.

Default Value:

"YYYY-MM-DD"

HTML Attribute:

displayformat

instance.headerFormat {String}

The format used to display the current month and year. See http://momentjs.com/docs/#/displaying/ for valid format string options. See Coral.Calendar#startDay

Default Value:

"MMMM YYYY"

HTML Attribute:

headerformat

instance.hidden {Boolean} Reflected

Whether this component is hidden or not.

Inherited From:

Coral.Component#hidden

Default Value:

false

HTML Attribute:

hidden

instance.invalid {Boolean} Reflected

Whether the current value of this field is invalid or not.

Inherited From:

Coral.mixin.formField#invalid

Default Value:

false

HTML Attribute:

invalid

instance.labelledBy {String}

Reference to a space delimited set of ids for the HTML elements that provide a label for the formField. Implementers should override this method to ensure that the appropriate descendant elements are labelled using the aria-labelledby attribute. This will ensure that the component is properly identified for accessibility purposes. It reflects the aria-labelledby attribute to the DOM.

Inherited From:

Coral.mixin.formField#labelledBy

Default Value:

null

HTML Attribute:

labelledby

instance.max {String | Date}

The maximum date that the Datepicker will accept as valid. It must not be less than its minimum. It accepts both date and string values. When a string is provided, it should match the Coral.Datepicker#valueFormat. See Coral.Calendar#max

Default Value:

null

HTML Attribute:

instance.min {String | Date}

The minimum date that the Datepicker will accept as valid. It must not be greated that its maximum. It accepts both date and string values. When a string is provided, it should match the Coral.Datepicker#valueFormat. See Coral.Calendar#min

Default Value:

null

HTML Attribute:

instance.name {String} Reflected

Name used to submit the data in a form.

Inherited From:

Coral.mixin.formField#name

Default Value:

HTML Attribute:

name

instance.placeholder {String} Reflected

Short hint that describes the expected value of the Datepicker. It is displayed when the Datepicker is empty.

Default Value:

HTML Attribute:

placeholder

instance.readOnly {Boolean} Reflected

Whether this field is readOnly or not. Indicating that the user cannot modify the value of the control. This is ignored for checkbox, radio or fileupload.

Inherited From:

Coral.mixin.formField#readOnly

Default Value:

false

HTML Attribute:

readonly

instance.required {Boolean} Reflected

Whether this field is required or not.

Inherited From:

Coral.mixin.formField#required

Default Value:

false

HTML Attribute:

required

instance.startDay {Number}

Defines the start day for the week, 0 = Sunday, 1 = Monday etc., as depicted on the calendar days grid. See Coral.Calendar#startDay

Default Value:

HTML Attribute:

startday

instance.type {Coral.Datepicker.type} Reflected

The type of datepicker to show to the user. See Coral.Datepicker.type

Default Value:

Coral.Datepicker.type.DATE

HTML Attribute:

type

instance.value {String}

The current value. When set to "today", the value is coerced into the client's local date expressed as string formatted in accordance to the set valueFormat. See Coral.Calendar#value

Default Value:

HTML Attribute:

value

instance.valueAsDate {Date}

The value of the element, interpreted as a date, or null if conversion is not possible.

Default Value:

null

instance.valueFormat {String}

The format to use on expressing the selected date as a string on the value attribute. The value will be sent to the server using this format. If an empty string is provided, then the default value per type will be used. See http://momentjs.com/docs/#/displaying/ for valid format string options.

Default Value:

"YYYY-MM-DD"

HTML Attribute:

valueformat

instance.variant {Coral.Datepicker.variant}

The datepicker's variant.

Default Value:

Coral.Datepicker.variant.DEFAULT

HTML Attribute:

variant

Methods

instance.get

Get the value of a property.

Parameters:

Name	Type	Description
property	String	The name of the property to fetch the value of.

Returns:

Property value. {*}

Inherited From:

Coral.Component#get

instance.hide

Hide this component.

Returns:: this, chainable {Coral.Component}

Inherited From:

Coral.Component#hide

instance.off

Remove an event listener.

Parameters:

Name	Type	Optional	Description
eventName	String	No	The event name to stop listening for.
selector	String	Yes	The selector that was used for event delegation.
func	function	No	The function that was passed to `on()`.
useCapture	Boolean	Yes	Only remove listeners with `useCapture` set to the value passed in.

Returns:

this, chainable. {Coral.Component}

Inherited From:

Coral.Component#off

instance.on

Add an event listener.

Parameters:

Name	Type	Optional	Description
eventName	String	No	The event name to listen for.
selector	String	Yes	The selector to use for event delegation.
func	function	No	The function that will be called when the event is triggered.
useCapture	Boolean	Yes	Whether or not to listen during the capturing or bubbling phase.

Returns:

this, chainable. {Coral.Component}

Inherited From:

Coral.Component#on

instance.remove

Non-destructively remove this element. It can be re-added by simply appending it to the document again. It will be garbage collected if there are no more references to it.

Inherited From:

Coral.Component#remove

instance.set

Set a single property.

Parameters:

Name	Type	Description
property	String	The name of the property to set.
value	*	The value to set the property to.
silent	Boolean	If true, events should not be triggered as a result of this set.

Returns:

this, chainable. {Coral.Component}

Inherited From:

Coral.Component#set

instance.show

Show this component.

Returns:: this, chainable {Coral.Component}

Inherited From:

Coral.Component#show

instance.trigger

Trigger an event.

Parameters:

Name	Type	Optional	Description
eventName	String	No	The event name to trigger.
props	Object	Yes	Additional properties to make available to handlers as `event.detail`.
bubbles	Boolean	Yes	Set to `false` to prevent the event from bubbling.
cancelable	Boolean	Yes	Set to `false` to prevent the event from being cancelable.

Returns: