Skip to main content



Use to help the user enter a date in a form.

This component wraps our ns-inputter component. Guidelines defined on the ns-inputter should also be followed when using this component. ns-inputter documentation

Datepicker Types#

ns-datepicker supports 2 types default and mask. When type is set to default the date-picker will display a calendar UI for selecting the date. On mobile/touch devices this will use the browsers native calendar. On desktop/non-touch devices it will use the Nucleus calendar component.

ns-datepicker type

Best practice#

Also see ns-inputter best practices

๐Ÿ’š Do's๐Ÿ’” Don'ts
Use the default type for picking a date from a rangeChange the date format
Use the default type for picking a date that the user might not be sure of (e.g. Next Friday)
Use the mask type for picking a dates that are well know to the user (e.g. Date of birth)

Considerations of best practices#

When the browser supports the <input type="date"> the format of the input will change depending on the settings of their device. For example users in UK will get the dd/mm/yyyy date format where as users in United States of America will get the m/d/yy date format. Regardless of the input format dates are always returned following the ISO 8601 date format

ISO 8601 date format#

This component uses the ISO 8601 date format: YYYY-MM-DD. This allows us to build upon the native <input type="date"> which also uses the same standard and provides a consistent approach to handling dates throughout nucleus.

Browser support#

Some browsers do not support type='date' (e.g. Safari on Desktop). The component detects if the browser supports this input and will fallback to use the mask type instead.


View example on Storybook

Component placement#

The ns-datepicker component can be used in the following components:


Also see ns-inputter specification

autocompleteautocompletestringoffValue to pass to the input autocomplete attribute.
helperhelperstringSee ns-inputter.
labellabelstringThe text to place in the label.
maxmaxstringThe maximum date allowed to be entered into the input. Must be in YYYY-MM-DD format. Validation will trigger if date is entered after this value
minminstringThe minimum date allowed to be entered into the input. Must be in YYYY-MM-DD format. Validation will trigger if date is before after this value
namenamestringdateSee ns-inputter.
typetypestringdefaultdefault, maskUse to select the input format. Default is the native date input.
validationvalidationarraySee ns-inputter. minDate and Max date are automatically applied if the min and max values are populated.
valuevaluestringThe value the input inside the component. This can be used to add an initial value.


  • Do you have insights or concerns to share? You can raise an issue via Github bugs.
  • See all the issues already raised via Github issues.

๐Ÿ’ฉ ๐ŸŽ‰ ๐Ÿฆ„ If you have any questions, contact us on Microsoft Teams in the Nucleus Design System channels.

Related links#