Datepicker A datepicker is used to enter a date or select one from a calendar.

A datepicker associates an input with a calendar. Selecting a date using the calendar will insert that date into the input, and editing that date in the input will update the calendar to match.

Table of contents


Usage guidelines

When to use
  • Datepickers should be used when a single date needs to be selected, or when a range needs to be selected via input as well as by calendar.
  • For calendar-only range selection, the calendar component may be used by itself.
Technical notes
  • Built on top of the Flatpickr.js library and uses Day.js for additional parsing.
  • All selected dates will be displayed in MMM D, YYYY format, but typed dates in the following formats are accepted and should be parsed correctly: MMMM D, YYYY, MMMM DD, YYYY, MMM D, YYYY, MMM DD, YYYY, MM/D/YYYY, MM/DD/YYYY, M/D/YYYY, M/DD/YYYY, MM.D.YYYY, MM.DD.YYYY, M.D.YYYY, M.DD.YYYY.
  • For range datepickers, formats can be mixed (e.g. MM/D/YYYY to M.D.YYYY).
  • For range datepickers, both hyphens and the word 'to' can be used to separate dates in the input (i.e. MM/D/YYYY to MM/D/YYYY and MM/D/YYYY - MM/D/YYYY).
  • This component does not render an instance of the calendar component inside of it. Instead, each component renders flatpickr instances that share styles.


Attributes

An asterisk next to a value denotes that it is the default value for that attribute. Unless noted otherwise, attributes should be added to the component element directly. Boolean attributes work based on their presence or absence from the component.

<res-component booleanAttribute stringAttribute="parameter">    
  <child-element></child-element>
</res-component>
AttributeTypeDescription
errorstringSet error state along with message

API

NameTypeDataDescription
valuepropertystringGets and sets the component's selected date value. The value is formatted as MM/DD/YYYY for basic date pickers, and YYYY-MM-DDT00:00:00Z for datetime pickers. Any string format parsable by new Date(...) may be set.
datetimepropertybooleanEnables calendar time selection, and switches the component's value format to YYYY-MM-DDT00:00:00Z.
mindatepropertystringGets and sets the component's minimum-allwed date. Any string format parseable by new Date(...) may be set.
maxdatepropertystringGets and sets the component's maximum-allwed date. Any string format parseable by new Date(...) may be set.
rangepropertybooleanEnables range selection.
calendarpropertyobjectReturns a Promise for the asynchronously loaded calendar. Call .then(calendar => {... on this member to reference the Flatpickr instance. (read only)

Notes

Required DOM

Without these, the component will throw an error on render.

  • <input> - Input element for date
Supported optional DOM

If added as children, these elements will receive specific styles and/or functionality.

  • <label> - Label element

History

VersionNote
0.24.0Adds range attribute to res-datepicker
0.23.0Change parsing engine to Day.js, allow more manual input date/datetime token formats
0.22.1Add type=button to datepicker toggle to fix behavior in form elements
0.15.10Adding support for datetime selection
0.15.2Fixed broken Vue rendering and added min/max allowed dates
0.15.0Added error state, date object, and sync'd flatpickr with input value
0.12.0Apply new spacing scale.
0.11.0Tweaks to accommodate new icon set.
0.7.0Refactored for use with external CSS and local Flatpickr module.
0.6.0No longer need to input full res-input-group. Just need label and input.
0.5.0Initial build to spec.