DatePicker

Library

Allium Design Systemweb-only

Repository

github.com/telus/allium-design-system

Package

npmjs.com/package/@telus-uds/ds-allium

Package version

1.14.0

Loading...

<DatePicker id="DatePicker" label="DatePicker" hint="Enter a Date" tooltip="This is a tooltip" />

<DatePicker id="DatePicker" label="DatePicker" hint="Enter a Date" tooltip="This is a tooltip" />

Introduction

import { DatePicker } from '@telus-uds/ds-allium'

Use DatePicker to select a date on a calendar.

Guidance

• Use overlay (default) variant to display in a modal container
• Use overlay variant whenever possible as it is the most accessible solution; the input form field is type-accessible and optimized for mobile customers
• Includes an input form field to allow manual key-in of dates
• Opens the modal when the input form field receives focus
• Width expands 100% until max-width of 340px

Uncontrolled component

warning

While DatePicker can be used as an uncontrolled component, using a ref to get the input's value behaves inconsistently between the default and inline version of the component. The inline version forwards the ref to a hidden input, but due to the limitations of the react-dates library, the default DatePicker attaches the ref to the component's wrapper.

It's recommended to use the onDateChange prop to get the current value of the input even when using it as an uncontrolled component. If you must rely on a ref to get the value on the input, you will need to find the input element nested inside the wrapper.

Loading...

function UncontrolledExample() { const [date, setDate] = useState() return ( <> <DatePicker id="DatePicker" label="DatePicker" onDateChange={setDate} /> Current Value: {date ? date.format('YYYY-MM-DD') : 'None'} </> ) }

function UncontrolledExample() {
  const [date, setDate] = useState()

  return (
    <>
      <DatePicker id="DatePicker" label="DatePicker" onDateChange={setDate} />
      Current Value: {date ? date.format('YYYY-MM-DD') : 'None'}
    </>
  )
}

Controlled component

If it is required that the state of the DatePicker be controlled by the application or other external methods, date and onDateChange props must be passed to the DatePicker.

Loading...

function ControlledExample() { const [date, setDate] = useState() return <DatePicker id="DatePicker" label="DatePicker" date={date} onDateChange={setDate} /> }

function ControlledExample() {
  const [date, setDate] = useState()

  return <DatePicker id="DatePicker" label="DatePicker" date={date} onDateChange={setDate} />
}

Accessibility

DatePicker has accessible controls and also uses the label prop to label the corresponding input.

Platform considerations

This component is currently only supported on web.

Props

Name	Type	Default	Description
copy	'en' | 'fr'	'en'	Whether the English or French copy will be used (e.g. for accessibility labels).
date	momentPropTypes .momentObj	undefined	A Moment instance representing the currently selected date, i.e. 'moment()'
feedback	string	undefined	A detailed description of validation error/success or additional instructions. Visual variant is determined based on the 'validation' prop.
hint	string	undefined	A short description of the expected input.
hintPosition	'inline' | 'below'	'inline'	Position of the hint relative to label. Use 'below' to display a larger hint below the label.
id*	string		A unique identifier.
inline	bool	false	A flag determining if the calendar picker is standalone or an input with overlay
isDayDisabled	func	undefined	A function determining whether a given date should be disabled @param {Moment} date The date to optionally disable @returns {bool}
label	string	undefined	The field label to be displayed above the calendar
onDateChange	func	() => {}	Event triggered every time a new date is clicked on @param {Moment} date The new date that was selected
tooltip	string	undefined	Content of an optional 'Tooltip'. If set, a tooltip button will be shown next to the label.
validation	'error' | 'success'	undefined	Use to visually mark an input as valid or invalid.

Figma

Variants

Inline

• Use Inline to display the DatePicker in a larger vieweable area; allows the customer to quickly and easily date availability
• Does not include an input form field
• Optimized for keyboard interaction and tablet touch
• Recommended for viewports greater than or equal to 576px

Loading...

<DatePicker id="DatePicker" inline />

<DatePicker id="DatePicker" inline />

Feedback

• Spotted a problem with this component? Raise an issue on GitHub
• See any existing issues for this component
• Contact the team on slack in #ds-allium-support