Date field

The Date Field allows users to enter a date by typing or by picking it from an integrated calendar popover. It supports configurable min/max constraints, locale-aware formatting, and a select-only mode that disables free typing.

Usage

Code

Accessibility

  <sl-date-field aria-label="Start date"></sl-date-field>

When to use

The following guidance describes when to use the date field component.

Precise date entry

Use the Date Field when the task requires an exact calendar date and you want to combine fast typing with visual confirmation through a calendar popover. It is ideal for booking dates, deadlines, birthdays, appointments, and any workflow where the date must be unambiguous.

Constrained date selection

Use the Date Field when only a specific date range is valid (for example, future dates only, dates within a school year, or dates between a start and end). The min and max attributes communicate the valid range visually in the calendar and through validation.

When not to use

Date fields may not be the best choice in the following scenarios:

Relative timeframes

Avoid the Date Field when only approximate periods or relative notions of time are needed (e.g., "next week", "this month", "in three days"). In these cases, prefer radio buttons, a segmented control, or a select that reflects a relative period.

Date ranges

For selecting a start and end date together, prefer a dedicated date range picker rather than two separate date fields, when available.

Anatomy

Item	Name	Description	Optional
1	Container	Wraps the input and trigger, provides the focus ring and error visuals.	no
2	Input	Editable field for typing a date.	no
3	Placeholder	Hint text when no value is set (e.g. the expected date format).	yes
4	Icon Button	Opens the calendar popover.	no
5	Calendar popover	Calendar overlay for picking a date visually.	no

States

Idle: Empty, showing the placeholder, or with a formatted date as the value.
Hover: Visual hover effects that show the user that the field is interactive.
Focus: Display the focus ring. It's shown when the field is active by clicking or keyboard navigation.
Invalid: When an incorrect or out-of-range value is entered, the field is styled to indicate the error.
Disabled: Non-interactive, muted.
Read-only: Visible value, no interaction.

Behavior

Free Typing (Default)

Users can type any valid date matching the locale-aware format. The component validates for format, parsability, and the optional min / max range when the field loses focus.

Click the calendar icon button or press Space/Enter on it to open the popover. Use the keyboard or pointer to focus a date and press Enter to select it. Pressing Escape closes the popover and returns focus to the input.

Select-only mode

When select-only is set, the input becomes read-only and users can only pick a date through the calendar popover. This is useful when you want to enforce valid input without relying on typed values.

Min and max

Dates outside the configured min / max range are disabled in the calendar and rejected by validation when typed.

Require confirmation

When require-confirmation is set, the user must explicitly confirm the selected date in the calendar before it becomes the field value. This is useful in workflows where accidental selection could trigger an action.

Calendar: Standalone calendar for date selection or date browsing.
Time Field: Companion component for selecting a time.
Text Field: For free-form text input.

  <sl-date-field aria-label="Appointment date"></sl-date-field>

Localization

The date format and the first day of the week follow the active locale (via Intl.DateTimeFormat).
You can override the first day of the week with the first-day-of-week attribute (0 for Sunday, 1 for Monday, etc.).

Min and max constraints

Use the min and max attributes to restrict the selectable date range. Dates outside the range are disabled in the calendar and rejected by validation.

Select-only mode

Set select-only to disable free typing in the input. Users can only pick a date through the calendar popover.

API

Form-aware date input with an integrated calendar popover. Supports localization, min/max constraints, validation and an optional select-only mode.

Properties

Name	Attribute	Type	Default	Description
`calendar`	-	`Calendar \| null`		The calendar element. This will return an instance of the calendar when the popover is shown or always when the calendar is slotted. Otherwise it will return undefined.
`customValidity`	`custom-validity`	`string \| undefined`		The error message to display when the control is invalid.
`dirty`	-	`boolean`	`false`	A control is dirty if the user has changed the value in the UI.
`disabled`	`disabled`	`boolean \| undefined`		Whether the date field is disabled; when set no interaction is possible.
`firstDayOfWeek`	`first-day-of-week`	`number \| undefined`	`1`	The first day of the week; 0 for Sunday, 1 for Monday.
`form`	-	`HTMLFormElement \| null`		The form associated with the control.
`formValue`	-	`unknown`		The value used when submitting the form.
`labels`	-	`NodeListOf<HTMLLabelElement>` \| null		The labels associated with the control.
`locale`	`locale`	`string`		The component's locale.
`max`	`max`	`Date \| undefined`	`undefined`	The maximum date selectable in the calendar.
`min`	`min`	`Date \| undefined`	`undefined`	The minimum date selectable in the calendar.
`month`	`month`	`Date \| undefined`		The current month to display.
`name`	`name`	`string \| undefined`		The name of the form control.
`nativeFormValue`	-	`FormValue`		Returns the form value as used in a native `<form>`. This is always a string, File, FormData or null.
`placeholder`	`placeholder`	`string \| undefined`	`undefined`	Placeholder text shown when there is no value and the field is not focused.
`readonly`	`readonly`	`boolean \| undefined`	`false`	Whether the date field is readonly.
`requireConfirmation`	`require-confirmation`	`boolean \| undefined`		When set, a "Confirm" button will be shown in the popover, and the user will need to click it to confirm their date selection.
`required`	`required`	`boolean \| undefined`	`false`	Whether the date field is a required field.
`selectOnly`	`select-only`	`boolean \| undefined`	`false`	Whether the component is select only. This means you cannot type in the inputs, but you can still pick a date via the popover.
`showValid`	-	`boolean`	`false`	Optional property to indicate the valid state should be shown.
`showValidity`	`show-validity`	`'valid' \| 'invalid' \| undefined`		Whether to show the validity state.
`showWeekNumbers`	`show-week-numbers`	`boolean \| undefined`	`false`	Shows the week numbers.
`touched`	-	`boolean`	`false`	A control is marked touched once the user has triggered a blur event on it.
`valid`	-	`boolean`		Returns whether the form control is valid or not.
`validationMessage`	-	`string`		String representing a localized (by the browser) message that describes the validation constraints that the control does not satisfy (if any). The string is empty if the control is not a candidate for constraint validation, or it satisfies its constraints. For true localization, see `getLocalizedValidationMessage()` instead.
`validity`	-	`ValidityState`		Returns the validity state the control is in.
`validityState`	-	`'valid' \| 'invalid' \| 'pending'`		Returns the current validity state.
`value`	`value`	`unknown \| undefined`		The selected date in the calendar.

Methods

Name	Parameters	Return	Description
`showPicker`		`void`	Show the date picker.
`hidePicker`		`void`	Hide the date picker.
`reportValidity`		`boolean`	Returns whether the control is valid. If the control is invalid, calling this will also cause an `invalid` event to be dispatched. After calling this, the control will also report the validity to the user.
`getLocalizedValidationMessage`		`string`	This returns a localized validation message. It does not support all `ValidityState` properties, since some require more context than we have here. If you need to support more, you can override this method in your own form control.
`setCustomValidity`	`message: string \| Promise<string>`	`void`	Sets a custom validation message for the form control. If the message is not an empty string, that will make the control invalid. By setting it to an empty string again, you can make the control valid again.

Events

Name	Event type	Description
`sl-blur`	`SlBlurEvent`	Emits when the focus leaves the component.
`sl-change`	`SlChangeEvent<Date \| undefined>`	Emits when the value changes.
`sl-focus`	`SlFocusEvent`	Emits when the component gains focus.
`sl-form-control`	`SlFormControlEvent`	Emits when the form control is added to the DOM.
`sl-update-state`	`SlUpdateStateEvent`	Emits when the UI state (dirty, pristine, touched or untouched) of the form control changes.
`sl-update-validity`	`SlUpdateValidityEvent`	Emits when the validity of the form control changes.
`sl-validate`	`SlValidateEvent`	Emits when the form control can be validated.

Keyboard interactions

The date field supports keyboard navigation for both the input and the calendar popover.

Command	Description
Tab	When focus is outside the date field, moves focus to the input. If focus is on the input, pressing Tab moves to the calendar trigger button, then to the next focusable element.
Space/Enter (on button)	Toggles the calendar popover when the button has focus.
Escape	Closes the calendar popover.
Arrow Left/Right (in calendar)	Moves focus to the previous or next day.
Arrow Up/Down (in calendar)	Moves focus to the same day in the previous or next week.
Page Up/Down (in calendar)	Moves focus to the same day in the previous or next month.
Shift + Page Up/Down (in calendar)	Moves focus to the same day in the previous or next year.
Home/End (in calendar)	Moves focus to the first or last day of the current month.
Enter (in calendar)	Selects the currently focused date and closes the popover.

WAI-ARIA

In the component itself we use multiple aria-attributes to assure the component works well with a range of assistive technologies. For some attributes however it is not possible for the Design System to add a meaningful value, because it relies on the context or way a component is used.

Attributes that we recommend you add in certain scenarios are mentioned below.

Attribute	Value	Description
`aria-label`	string	Defines a string that labels the date field. Required when not wrapped with `sl-form-field` and there is no `sl-label` component.
`aria-labelledby`	string	References the ID of the element that labels the date field.
`aria-required`	boolean	Informs the user that an element is required. When set to ‘true’, screen readers notify users that the element is required. If there is already a `required` attribute added, it is recommended to avoid adding `aria-required`.
`aria-disabled`	boolean	Announces the date field as disabled with a screen reader. See note below about difference from the `disabled` attribute.

Notes:

The aria-disabled should not be used as a one-for-one replacement for the disabled attribute because they have different functionalities:

The disabled attribute dims the date field visually, removes it from tab focus, prevents all interactions, and announces it as disabled.
The aria-disabled attribute only announces the disabled state but doesn't prevent interaction or remove focus.

Use disabled for true disabled states, use aria-disabled only if you need the element to remain in the tab sequence for specific accessibility reasons.

Interactive example