ns-datepicker

Introduction#

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 range	Change 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.

Usage#

View example on Storybook

Component placement#

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

Specification#

Also see ns-inputter specification

Attribute	Type	Default	Options	Description
`autocomplete`	`string`	"off"		Value to pass to the input autocomplete attribute.
`helper`	`string`			See ns-inputter.
`label`	`string`			The text to place in the label.
`max`	`string`			The 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
`min`	`string`			The 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
`name`	`string`	"date"		See ns-inputter.
`type`	`string`	"default"	`default`, `mask`	Use to select the input format. Default is the native date input.
`validation`	`array`			See ns-inputter. minDate and Max date are automatically applied if the min and max values are populated.
`value`	`string`			The value the input inside the component. This can be used to add an initial value.

Slots	Type
`tip-details`	`div`

Design Tokens

You can change the branded look and feel of the ns-datepicker by modifying these options in the design tokens.

Read more about design tokens in our getting started guide.

{
  "background-color": "#FFFFFF",
  "border-color": "#C3CED5 ",
  "icon": {
    "color": "#002F87",
    "spacer": {
      "outside-right": "0.5rem"
    }
  },
  "hover": {
    "icon": {
      "color": "#111518"
    }
  },
  "native-date": {
    "spacer": {
      "inside-right": "2rem"
    }
  },
  "toggle": {
    "spacer": {
      "outside-top": "0.5rem"
    }
  },
  "calendar-button": {
    "typography": "action",
    "color": "#004ECC",
    "focus": {
      "color": "#004ECC",
      "outline-color": "#FFC72C"
    },
    "hover": {
      "color": "#002F87",
      "text-decoration-color": "#002F87"
    },
    "theme": "white"
  },
  "header": {
    "typography": "action",
    "color": "#111518",
    "background-color": "#F3F5F7",
    "heading": {
      "spacer": {
        "outside-top": "0",
        "outside-bottom": "0"
      }
    },
    "spacer": {
      "inside-top": "0.5rem",
      "inside-right": "0.75rem",
      "inside-bottom": "0.5rem",
      "inside-left": "0.75rem"
    },
    "border-color": "#C3CED5 ",
    "border-width": "0.125rem"
  },
  "dialog": {
    "spacer": {
      "inside-top": "0",
      "inside-right": "0",
      "inside-bottom": "0",
      "inside-left": "0"
    },
    "calendar": {
      "spacer": {
        "inside-top": "0.5rem",
        "inside-bottom": "0.5rem",
        "tennis-court": {
          "inside-left": "1rem",
          "inside-right": "1rem"
        }
      }
    }
  },
  "close": {
    "color": "#111518",
    "focus-outline-color": "#FFC72C",
    "spacer": {
      "inside-top": "0.25rem",
      "inside-right": "0.25rem",
      "inside-bottom": "0.25rem",
      "inside-left": "0.25rem"
    }
  },
  "border-width": "0.125rem"
}

Feedback#

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.