{ "_copyright": "Copyright (c) 2026, Salesforce, Inc., All rights reserved. For full license text, see the LICENSE.txt file", "$schema": "https://slds.lightningdesignsystem.com/schemas/uif-system.v1.json", "apiVersion": "1.0.0", "name": "Datepicker", "description": "A datepicker is a text input paired with a calendar dropdown that lets users type or pick a single date.", "structure": { "name": "root", "restrict": [ "div" ], "description": "Initiates a datepicker component.", "children": [ { "name": "label", "restrict": [ "label" ], "description": "Visible label for the date input.", "attributes": { "bound": { "for": { "prop": "inputId" } }, "static": { "class": "slds-form-element__label" } } }, { "name": "requiredIndicator", "restrict": [ "abbr" ], "description": "Asterisk marker rendered inside the label when the field is required.", "renderWhen": { "prop": "required", "eq": "true" }, "attributes": { "static": { "class": "slds-required", "title": "required", "aria-hidden": "true" } } }, { "name": "helpTooltip", "restrict": [ "div" ], "description": "Optional help-icon button with a popover tooltip describing the expected date format.", "children": [ { "name": "helpButton", "restrict": [ "button" ], "description": "Help icon button that toggles the tooltip.", "attributes": { "static": { "class": "slds-button slds-button_icon" } } }, { "name": "helpPopover", "restrict": [ "div" ], "description": "Tooltip popover associated with the help button.", "attributes": { "static": { "role": "tooltip", "class": "slds-popover slds-popover_tooltip slds-nubbin_bottom-left" } }, "children": [ { "name": "helpPopoverBody", "restrict": [ "div" ], "description": "Body text of the help tooltip.", "attributes": { "static": { "class": "slds-popover__body" } } } ] } ], "attributes": { "static": { "class": "slds-form-element__icon" } } }, { "name": "control", "restrict": [ "div" ], "description": "Form-element control wrapper that holds the input and the trigger icon button.", "children": [ { "name": "input", "restrict": [ "input" ], "description": "Text input where the user types or sees the selected date.", "attributes": { "static": { "type": "text", "class": "slds-input" }, "bound": { "id": { "prop": "inputId" }, "value": { "prop": "value" }, "placeholder": { "prop": "placeholder" } } } }, { "name": "triggerButton", "restrict": [ "button" ], "description": "Icon button that opens the calendar dropdown.", "attributes": { "bound": { "title": { "prop": "openCalendarLabel" } }, "static": { "class": "slds-button slds-button_icon slds-input__icon slds-input__icon_right" } }, "children": [ { "name": "triggerIcon", "restrict": [ "svg" ], "description": "Calendar event icon inside the trigger button.", "attributes": { "static": { "class": "slds-button__icon", "aria-hidden": "true" } } }, { "name": "triggerAssistiveText", "restrict": [ "span" ], "description": "Visually-hidden label announcing the trigger action.", "attributes": { "static": { "class": "slds-assistive-text" } } } ] } ], "attributes": { "static": { "class": "slds-form-element__control slds-input-has-icon slds-input-has-icon_right" } } }, { "name": "help", "restrict": [ "div" ], "description": "Format-hint or error text rendered below the input.", "attributes": { "static": { "class": "slds-form-element__help slds-assistive-text" } } }, { "name": "dropdown", "restrict": [ "div" ], "description": "Calendar dropdown dialog (popover) anchored to the input.", "attributes": { "static": { "role": "dialog", "class": "slds-datepicker slds-dropdown slds-dropdown_left" }, "bound": { "aria-hidden": { "prop": "isClosed" }, "aria-label": { "prop": "dialogLabel" } } }, "children": [ { "name": "header", "restrict": [ "div" ], "description": "Month/year navigation header at the top of the calendar.", "children": [ { "name": "monthNav", "restrict": [ "div" ], "description": "Inline group containing the previous-month button, the current month heading, and the next-month button.", "children": [ { "name": "prevButtonWrapper", "restrict": [ "div" ], "description": "Alignment wrapper around the previous-month button.", "attributes": { "static": { "class": "slds-align-middle" } } }, { "name": "prevButton", "restrict": [ "button" ], "description": "Previous month button.", "attributes": { "bound": { "title": { "prop": "prevMonthLabel" } }, "static": { "class": "slds-button slds-button_icon slds-button_icon-container" } }, "children": [ { "name": "prevIcon", "restrict": [ "svg" ], "description": "Left chevron icon inside the previous-month button.", "attributes": { "static": { "class": "slds-button__icon", "aria-hidden": "true" } } }, { "name": "prevAssistiveText", "restrict": [ "span" ], "description": "Visually-hidden label for the previous-month button.", "attributes": { "static": { "class": "slds-assistive-text" } } } ] }, { "name": "monthYear", "restrict": [ "h2" ], "description": "Current month label, announced as a live region when the month changes.", "attributes": { "static": { "aria-atomic": "false", "aria-live": "polite", "class": "slds-align-middle" } } }, { "name": "nextButtonWrapper", "restrict": [ "div" ], "description": "Alignment wrapper around the next-month button.", "attributes": { "static": { "class": "slds-align-middle" } } }, { "name": "nextButton", "restrict": [ "button" ], "description": "Next month button.", "attributes": { "bound": { "title": { "prop": "nextMonthLabel" } }, "static": { "class": "slds-button slds-button_icon slds-button_icon-container" } }, "children": [ { "name": "nextIcon", "restrict": [ "svg" ], "description": "Right chevron icon inside the next-month button.", "attributes": { "static": { "class": "slds-button__icon", "aria-hidden": "true" } } }, { "name": "nextAssistiveText", "restrict": [ "span" ], "description": "Visually-hidden label for the next-month button.", "attributes": { "static": { "class": "slds-assistive-text" } } } ] } ], "attributes": { "static": { "class": "slds-datepicker__filter_month slds-grid slds-grid_align-spread slds-grow" } } }, { "name": "yearGroup", "restrict": [ "div" ], "description": "Year picker group at the right side of the calendar header.", "children": [ { "name": "yearLabel", "restrict": [ "label" ], "description": "Visually-hidden label for the year select.", "attributes": { "static": { "class": "slds-assistive-text" } } }, { "name": "yearSelectWrapper", "restrict": [ "div" ], "description": "Native-select wrapper providing the visual chevron affordance.", "attributes": { "static": { "class": "slds-select_container" } } }, { "name": "yearSelect", "restrict": [ "select" ], "description": "Native select listing selectable years.", "children": [ { "name": "yearOption", "restrict": [ "option" ], "description": "A single year choice.", "slot": { "name": "yearOptions" } } ], "attributes": { "static": { "class": "slds-select" } } } ], "attributes": { "static": { "class": "slds-shrink-none" } } } ], "attributes": { "static": { "class": "slds-datepicker__filter slds-grid" } } }, { "name": "calendar", "restrict": [ "table" ], "description": "Calendar grid.", "attributes": { "static": { "role": "grid", "class": "slds-datepicker__month" }, "bound": { "aria-multiselectable": { "prop": "multiSelectable" } } }, "children": [ { "name": "weekdayHeaders", "restrict": [ "thead" ], "description": "Weekday column headers.", "children": [ { "name": "weekdayRow", "restrict": [ "tr" ], "description": "Single row of weekday names." }, { "name": "weekdayHeader", "restrict": [ "th" ], "description": "Column header for one weekday.", "attributes": { "static": { "scope": "col" } }, "children": [ { "name": "weekdayAbbr", "restrict": [ "abbr" ], "description": "Abbreviation expanding the short weekday name to the full name." } ] } ] }, { "name": "days", "restrict": [ "tbody" ], "description": "Calendar day cells, organized by week.", "slot": { "name": "default" }, "children": [ { "name": "weekRow", "restrict": [ "tr" ], "description": "One week of date cells." }, { "name": "dayCell", "restrict": [ "td" ], "description": "A single date cell in the grid.", "attributes": { "static": { "role": "gridcell" }, "bound": { "aria-selected": { "prop": "isSelected" }, "aria-label": { "prop": "dateLabel" }, "aria-current": { "prop": "isToday" } } }, "children": [ { "name": "dayLabel", "restrict": [ "span" ], "description": "Visible day-of-month number inside the cell.", "attributes": { "static": { "class": "slds-day" } } } ] } ] } ] }, { "name": "footer", "restrict": [ "button" ], "description": "Today link button rendered below the grid.", "renderWhen": "slotFilled", "slot": { "name": "footer" }, "attributes": { "static": { "class": "slds-button slds-align_absolute-center slds-text-link" } } } ] } ], "attributes": { "static": { "class": "slds-form-element slds-dropdown-trigger slds-dropdown-trigger_click" } }, "modifiers": [ { "name": "open", "attribute": "class", "value": "slds-is-open" }, { "name": "hasError", "attribute": "class", "value": "slds-has-error" } ], "variants": [ { "name": "layout", "description": "Outer wrapper layout. Single renders a bare form-element; range wraps two form-elements in a compound fieldset; in-datatable embeds the form-element inside an SLDS data table cell.", "options": [ { "value": "single", "class": "" }, { "value": "range", "class": "slds-form slds-form_compound" }, { "value": "inDatatable", "class": "slds-table" } ] } ] }, "states": [ { "name": "open", "type": "boolean", "description": "Whether the calendar dropdown is currently visible." }, { "name": "disabled", "type": "boolean", "aria": "aria-disabled", "description": "Whether the datepicker is disabled." }, { "name": "required", "type": "boolean", "aria": "aria-required", "description": "Whether a value is required." }, { "name": "hasError", "type": "boolean", "description": "Whether the datepicker has a validation error." }, { "name": "selectedDate", "type": "enum", "aria": "aria-selected", "description": "Currently selected date.", "options": [] }, { "name": "focusedDate", "type": "enum", "description": "Currently focused date in the grid.", "options": [] }, { "name": "today", "type": "boolean", "aria": "aria-current", "description": "Whether a date cell represents today." }, { "name": "adjacentMonth", "type": "boolean", "description": "Whether a date belongs to an adjacent (previous/next) month." }, { "name": "multiRowSelection", "type": "boolean", "description": "Whether a week row contains multiple selected dates spanning a range." }, { "name": "multiSelection", "type": "boolean", "description": "Whether a row contains a single selected cell that participates in a range." }, { "name": "selectedMulti", "type": "boolean", "description": "Whether a cell is part of a multi-cell range selection." } ], "accessibility": { "requirements": [ { "id": "dialog-role", "description": "Calendar dropdown must use role='dialog' with an aria-label naming the visible month." }, { "id": "grid-role", "description": "Calendar must have role='grid' and announce multi-selectability via aria-multiselectable." }, { "id": "live-month", "description": "Month heading must use aria-live='polite' so screen readers announce month changes." }, { "id": "keyboard-navigation", "description": "Arrow keys navigate dates; Enter selects; Esc closes the dropdown." }, { "id": "aria-selected", "description": "Every date cell must carry aria-selected (true/false)." }, { "id": "aria-current-date", "description": "The cell representing today must have aria-current='date'." }, { "id": "trigger-assistive-text", "description": "The trigger icon button must include visually-hidden text announcing 'Select a date'." } ] }, "extensions": { "com.salesforce-ux": { "dateAdded": "2015-09-04", "genReady": false, "lbc": "lightning-datepicker" } }, "cssSource": "./datepicker.css", "styleApi": { "status": "stable", "ready": true }, "stateClasses": [ { "state": "open", "class": "slds-is-open" }, { "state": "hasError", "class": "slds-has-error" }, { "state": "selectedDate", "class": "slds-is-selected" }, { "state": "focusedDate", "class": "slds-has-focus" }, { "state": "today", "class": "slds-is-today" }, { "state": "adjacentMonth", "class": "slds-day_adjacent-month" }, { "state": "selectedMulti", "class": "slds-is-selected-multi" }, { "state": "multiSelection", "class": "slds-has-multi-selection" }, { "state": "multiRowSelection", "class": "slds-has-multi-row-selection" } ] }