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 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 select or radio buttons 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 vailable.

Only calendar

Do not use the Date Field when the date selection needs to be shown directly in the layout instead of inside a dropdown. Use the Calendar when the visual date picker is the main interaction.

Anatomy

Item	Name	Description	Optional
1	Label	Describes the purpose of the field and helps users understand which date to enter.	yes
2	Input field	Main input area where users can type a date or view the selected value.	no
3	Placeholder	Hint shown inside the field when no value is selected, usually showing the expected date format.	yes
4	Picker button	Icon-only button that opens the Picker dropdown for visual date selection.	no
5	Clear button	Icon-only button that appears when a date is selected and clears the current value.	yes
6	Picker	Dropdown connected to the field that contains the Calendar and optional picker panels.	yes
7	Calendar	Visual date picker used inside the Picker to navigate and select a date.	yes

States

These states describe what users see when the Date Field is available.

Idle: Empty, showing the placeholder, or with a formatted date as the value if the the field is filled.
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, the field is visible but unavailable for interaction.

Figma Properties

These properties describe the Figma setup for the Date Field. Some properties represent real UI behaviour, while others are only used to preview or compose the component in Figma.

sl-date_field

Main component used to compose the Date Field and preview the closed or open Picker state.

Item	Options	Description
Open	`false` `true`	Figma-only preview property that shows or hides the Picker dropdown. The open state is triggered by interaction in the product UI.

sl-date_field-variants

Nested field component used to control the visible field content, label visibility, and clear action in Figma.

Item	Options	Description
Text	`text`	Figma text property for the visible field value. Represents the selected or typed date shown in the field.
Placeholder text	`text`	Figma text property for the placeholder shown when the field has no value.
Label	`boolean`	Shows or hides the label above the field.
Clear	`boolean`	Shows or hides the clear button in Figma. In product UI, the clear button appears when a date is selected.
Variant	`Default`	Main visual style currently represented in Figma.
Size	`MD`	Figma size property. The current component setup represents the medium field size.
Placeholder	`false`	Figma setup property for previewing the placeholder state. The product UI should rely on the field value and placeholder text.

sl-base-label

Nested label component used to configure the label content, hint, and optional information shown above the field.

Item	Options	Description
Label	`text`	Sets the label text.
Show Info	`boolean`	Shows or hides the info icon next to the label.
Show Hint	`boolean`	Shows or hides the hint text.
Hint	`text`	Sets the hint content shown with the label.
Optional	`false`	Figma property present in the nested label setup. Not currently exposed as an alternative option in this component.
Required	`false`	Figma property present in the nested label setup. Not currently exposed as an alternative option in this component.

sl-date-calendar

Nested Calendar component shown inside the Picker. It is shared with the Range Field and controls the visual date selection experience.

Item	Options	Description
View	`Days` `Months` `Years`	Switches the Calendar between day, month, and year selection views.
Footer	`boolean`	Shows or hides the footer area for quick actions such as selecting today or clearing the date.

Calendar Day Grid

Nested Calendar properties are used to compose and preview date, month, and year selection states inside Figma.

Item	Options	Description
Weeks Number	`boolean`	Shows or hides week numbers in the day grid.

Calendar Day Toggle Button

Nested Calendar properties are used to compose and preview date, month, and year selection states inside Figma.

Item	Options	Description
Type	`Default` `Secondary` `Disabled`	Previews the visual role or availability of Calendar items.
Selected	`False` `True`	Previews whether a day, month, or year item is selected.
Today Indicator	`boolean`	Shows the marker for today in the day view.
Focus	`boolean`	Shows the focus ring for a Calendar item.
Event Indicator	`boolean`	Shows a small indicator under a day item.
Current Indicator	`boolean`	Shows the marker for the current month or year.

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

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 using the confirm button in the popover footer before it is set as 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