Date
pivot-date is a single-date form control built on the native HTML
<input type="date"> element. It provides Pivot field labeling, helper and
error messaging, required and disabled states, native browser date-picker
behavior, and form association through ElementInternals.
Quick Start
<pivot-date
pivot-name="start-date"
pivot-label="Start date"
pivot-helper-text="Use the date picker or enter the date in your local format."
pivot-required
></pivot-date>Using the field-label-tooltip slot
pivot-date accepts a single named slot, field-label-tooltip. The
<slot name="field-label-tooltip"> that receives it is rendered directly in
pivot-date’s own shadow root by the shared renderFieldLabel() helper (see
Implementation Notes). It is
designed to hold a single pivot-field-label-tooltip element:
<pivot-date pivot-name="effective-date" pivot-label="Effective date">
<pivot-field-label-tooltip
slot="field-label-tooltip"
pivot-tooltip-popover-header="About effective dates"
>
<pivot-text>
Choose the date on which this change should take effect.
</pivot-text>
</pivot-field-label-tooltip>
</pivot-date>Tooltip content should be supplemental. Put information required to complete
the field in pivot-helper-text so it is visible without opening a tooltip.
pivot-date tracks whether this slot has assigned content (willUpdate
checks each child for slot="field-label-tooltip") and only renders the
<slot> element when content is present. The slot="field-label-tooltip"
attribute is required — a <pivot-field-label-tooltip> child without it is
not rendered, and the component logs a console warning naming the element.
Using the pivot-date-change event
document
.querySelector("pivot-date")
.addEventListener("pivot-date-change", (event) => {
console.log(event.detail.value);
});pivot-date-change is dispatched from the native <input type="date">'s
input event, not its change event, so it can fire more than once as the
browser commits each part of the date (for example, selecting a date from the
picker or completing the last segment typed by hand). event.detail.value is
the input’s current value: either an empty string, or a date normalized by the
browser to YYYY-MM-DD regardless of the user’s locale. The value is a
date only — it carries no time-of-day or time zone component, so avoid
parsing it as if it did.
Form Association
pivot-date sets static formAssociated = true, making it a form-associated
custom element. This means:
- Its value is included in
FormDatausingpivot-nameas the key. pivot-datedefines its owncheckValidity()/reportValidity()methods, so you can validate the element directly without going through the containing form. Both also propagate into the parent form’s validity state, since the native date input’s validity is forwarded toElementInternalsafter every input.- Form reset clears the date, and any native validation message currently
displayed, through
formResetCallback. - When a parent fieldset or form disables the component,
formDisabledCallbackupdates the native date input.
name attribute
The component mirrors pivot-name to the host element’s native name
attribute on update. This is required for the form-associated custom element to
use the correct key when creating FormData. Do not manually set name on the
host; it will be overwritten.
Methods
checkValidity()
Returns boolean. Checks the current constraint-validation state of the native date input (kept in sync with ElementInternals after every input) and returns whether it is currently valid. When the field is invalid, the browser fires an invalid event on the host, and the validation message is rendered inline below the field — see Validation and Integration.
const date = document.querySelector("pivot-date[pivot-name='start-date']");
date.checkValidity(); // true | falsereportValidity()
Returns boolean. Performs the same validity check as checkValidity(). The browser’s native validation bubble is suppressed; when the field is invalid, the validation message is rendered inline below the field instead, exactly as with checkValidity().
const date = document.querySelector("pivot-date[pivot-name='start-date']");
date.reportValidity(); // renders the validation message inline if invalidBoth methods reflect the same validity state that the containing form’s checkValidity() / reportValidity() aggregate — see Form Association.
CSS Parts
| Part | Element | Description |
|---|---|---|
container |
Outer <div> |
Wraps the label, date input, and helper or error message. |
Implementation Notes
pivot-nameis required. The component throws at update time whenpivot-nameis missing or blank.- The rendered control is a native
<input type="date">. The browser and operating system determine the visible date format and picker UI. - The date value submitted to a form is normalized by the browser to
YYYY-MM-DD, regardless of the user’s locale. The value contains a date, not a time or time zone. pivot-min,pivot-max, andpivot-stepare forwarded to the native date input. Use valid date strings inYYYY-MM-DDformat forpivot-minandpivot-max.pivot-stepis a positive number expressed in days. The component does not support the nativeanykeyword forstep.- Label rendering — including the label text, optional/required indicators,
and tooltip placement — is produced by the shared
renderFieldLabel()helper (../field-label/render-field-label.ts), whichpivot-datecalls directly from its ownrender()method. - Helper and error message rendering is delegated to
pivot-field-helper-message. Error text —pivot-error-textor the browser’s native validation message — takes priority over helper text while it is shown. pivot-dateis a form-associated custom element. It participates in form submission, reset, and validation throughElementInternalsand works insidepivot-form-containerwithout additional setup.
Date constraints
<pivot-date
pivot-name="appointment-date"
pivot-label="Appointment date"
pivot-min="2026-09-01"
pivot-max="2026-09-30"
pivot-step="7"
pivot-helper-text="Choose a date in September 2026."
></pivot-date>pivot-min and pivot-max constrain the permitted date range. If both are
provided, the minimum must not be later than the maximum. pivot-step accepts a
positive number of days between valid dates, such as 7 for weekly intervals.
When omitted, the native date-input default is one day. Invalid dates produce
native constraint-validation failures, which are forwarded to
ElementInternals.
Validation and Integration
const form = document.querySelector("pivot-form-container form");
form.checkValidity();
form.reportValidity();
const data = new FormData(form);
console.log(data.get("start-date")); // e.g. "2026-08-24"To validate a single pivot-date field independently of the containing form,
call checkValidity() / reportValidity() on the element itself.
Native validation messages
pivot-date intercepts the browser’s invalid event and calls
preventDefault() on it, so the browser’s native validation bubble never
appears. Instead, the browser’s validationMessage for the failing constraint
(e.g. pivot-required, pivot-min, pivot-max, pivot-step) is rendered
below the field by pivot-field-helper-message, using the same error icon and
styling as pivot-error-text. This happens whenever an invalid event fires
for the field — on a blocked form submission, on form.checkValidity() /
form.reportValidity(), or on the element’s own checkValidity() /
reportValidity().
<form>
<pivot-date
pivot-name="start-date"
pivot-label="Start date"
pivot-min="2026-09-01"
pivot-required
></pivot-date>
<button type="submit">Submit</button>
</form>
<!-- Submitting empty, or with a date before 2026-09-01, renders the browser's
validation message below the field in Pivot error styling. -->The message is captured when the invalid event fires. It is removed as soon
as the field becomes valid again and when the parent form is reset. If the
field stays invalid but fails a different constraint, the displayed message
updates the next time validation runs.
Error state precedence
The field is in its error state — error styling, aria-invalid="true", and a
has-error attribute on the host — when pivot-error is set,
pivot-error-text has a value, or a native validation message is displayed.
When both pivot-error-text and a native validation message are present,
pivot-error-text is the message shown. Setting pivot-error alone applies
the error styling without a message, and any pivot-helper-text stays
visible. The component manages has-error itself; don’t set or remove it
manually.
pivot-error and pivot-error-text do not affect the element’s validity —
use them to display errors from your own (e.g. server-side) validation.
The native date input’s value is empty until a date is selected. The submitted
value is a date string in YYYY-MM-DD format, while the visible representation
may be localized. Treat the submitted value as a date-only value and avoid
interpreting it as a timestamp without an explicit time-zone policy.
Accessibility
When the field is in its error state (pivot-error, pivot-error-text, or a
displayed native validation message — see
Error state precedence), aria-invalid="true" is
applied to the native date input (WCAG 4.1.2), and reset to "false" when the
error state is cleared. When helper or error text is present, the native date input is linked to
pivot-field-helper-message via aria-describedby so assistive technology
announces the message on focus (WCAG 1.3.1, 4.1.3). The shared
renderFieldLabel() helper renders the <label for="..."> directly into
pivot-date’s own shadow root, alongside the date <input id="...">, so
their for/id association is valid (WCAG 1.3.1, 4.1.2) — clicking the
label moves focus to the input. The input’s accessible name is nonetheless
set directly via aria-label — pivot-aria-label if provided, otherwise the
visible pivot-label text — since aria-label always takes precedence over
an associated <label> in the accessible name computation. Avoid setting
pivot-aria-label to text that differs from a visible pivot-label, since
that produces a mismatch between the visible label and the accessible name
(WCAG 2.5.3, Label in Name). pivot-date uses native label and input
semantics and does not implement a custom ARIA date-picker dialog, so the
WAI-ARIA date-picker dialog pattern is not a direct implementation
requirement for this component.
Screen Reader Behavior
Screen readers encounter a single native date input with no accessible role
of its own beyond the native input[type="date"] role the browser exposes.
Its accessible name comes from aria-label, not from the native label
association, even though that association is valid: the <label for="...">
rendered by renderFieldLabel() and the date <input id="..."> share
pivot-date’s own shadow root, so the for/id pairing does resolve per
the HTML label-association algorithm — but aria-label on the input takes
precedence over an associated <label> in the accessible name computation
regardless, so the visible label text is not itself the source of the
announced name. The rest of the field’s structure — helper or error text —
lives in the pivot-field-helper-message child and is associated to the
input through aria-describedby. Because aria-invalid and
aria-describedby are recalculated on every render, a screen reader
announces the current error or helper state the next time the field receives
focus. Separately, pivot-field-helper-message renders its error text with
role="alert" (WCAG 4.1.3, Status Messages), so validation errors are also
announced as soon as pivot-error-text or a native validation message
appears, without requiring the date field to regain focus — see that component’s README for
the exact behavior and its initial-render caveat.
Keyboard Navigation
The browser and operating system own the date input’s picker and segmented
editing behavior. Keyboard commands, displayed format, and picker appearance
can differ across browsers and platforms; pivot-date does not attach its own
keyboard handlers or implement a calendar-dialog key map. Users can generally:
- focus the field through normal tab navigation (WCAG 2.1.1);
- type or edit the date’s segments using the native control’s arrow-key and numeric-entry behavior;
- open and operate the native picker using the platform’s supported controls;
- use the associated label to focus the date field by clicking it; and
- clear the value using the native input’s clear control or by editing it out.
Focus Management
pivot-date does not implement any focus-management logic of its own — no
explicit .focus()/.blur() calls, tabindex, or focus trap. It inherits
delegatesFocus: true from PivotBase’s shadow root options, so calling
.focus() on the pivot-date host delegates focus into the shadow root’s
first focusable element — the native date input — and :focus/
:focus-visible on the host reflect that internal focus state. Because the
rendered <label> and the date input share pivot-date’s own shadow
root (see Screen Reader Behavior above), the
for/id association between them is valid, so clicking or tapping the
label text natively moves focus to the input — the same as clicking the
input directly, or calling .focus() on the host.
When form submission or reportValidity() fails, focus is not moved to the
field — the component cancels the invalid event to suppress the native
bubble, which also cancels the browser’s built-in focus-on-invalid behavior.
If you want the first invalid field focused on submit, handle it in your own
code — for example, listen for invalid on the form in the capture phase (the
event does not bubble) and call .focus() on the first host that fires it.
The rendered error message is still announced via role="alert" (WCAG 3.3.1).
Related Components
References
- WAI-ARIA Authoring Practices: Date Picker Dialog Example
- Carbon Design System: Date picker usage
- MDN:
<input type="date"> - Nielsen Norman Group: Date-Input Form Fields
API Reference
Props
| Name | Type | Default | Description |
|---|---|---|---|
pivot-label |
string |
"" |
This will create an attribute: pivot-label="value" |
pivot-aria-label |
string |
"" |
The accessible name for the date input. The date `<input>` and the `<label>` produced by the shared `renderFieldLabel()` helper share this component's own shadow root, so their `for`/`id` association is valid — but `aria-label` still takes precedence over an associated `<label>` in the accessible name computation, so the input's accessible name always comes from `aria-label` rather than the visible label text. `aria-label` falls back to `pivotLabel` automatically when this is unset, so this only needs to be set to override that text (for example, when no visible `pivotLabel` is provided at all). |
pivot-helper-text |
string | null |
null |
This will create an attribute: pivot-helper-text="value" |
pivot-error-text |
string | null |
null |
This will create an attribute: pivot-error-text="value" |
pivot-name |
string |
"" |
This will create an attribute: pivot-name="value" |
pivot-id |
string |
"" |
This will create an attribute: pivot-id="value" |
pivot-min |
string |
"" |
This will create an attribute: pivot-min="value" |
pivot-max |
string |
"" |
This will create an attribute: pivot-max="value" |
pivot-step |
number |
undefined |
This will create an attribute: pivot-step="value" |
pivot-disabled |
boolean |
false |
Presence of attribute means true: <pivot-input pivot-disabled> |
pivot-optional |
boolean |
false |
Presence of attribute means true: <pivot-input pivot-optional> |
pivot-required |
boolean |
false |
Presence of attribute means true: <pivot-input pivot-required> |
pivot-error |
boolean |
false |
Presence of attribute means true: <pivot-input pivot-error> |
Slots
| Name | Description |
|---|---|
field-label-tooltip |
Optional tooltip content placed beside the field label |
Events
| Name | Type | Description |
|---|---|---|
pivot-date-change |
CustomEvent |
Fired on input with detail `{ value: string }`, the native date input's current value normalized to YYYY-MM-DD (or empty) |
CSS Custom Properties
| Name | Description |
|---|---|
--component-field-gap |
Gap between the label row, date input row, and helper or error message within the outer grid container. |
--global-interaction-md |
Minimum block size of the date input. |
--typography-icon-md-size |
Size used to calculate the date input's reserved inline-end padding. |
--component-field-control-general-inset-x |
Horizontal padding of the date input; also used to calculate the reserved inline-end padding. |
--component-field-control-general-inset-y |
Vertical padding of the date input. |
--typography-constants-body-family |
Font family of the date input text. |
--typography-body-md-size |
Font size of the date input text. |
--typography-body-md-height |
Line height of the date input text. |
--component-field-control-input |
Text color of the date input value. |
--component-field-control-surface |
Background color of the date input. |
--component-field-control-border-color |
Border color of the date input in the default state. |
--component-field-control-border-width |
Border width of the date input, applied in both the default and error states. |
--component-field-control-general-radius |
Border radius of the date input. |
--component-field-control-surface-disabled |
Background and border color when the date input is disabled. |
--component-field-control-surface-error |
Background color applied in the error state. |
--component-field-control-border-color-error |
Border color applied in the error state. |
Basic date input
<pivot-date pivot-name="basic-date" pivot-label="Date"></pivot-date>Helper text (pivot-helper-text)
<pivot-date
pivot-name="helper-date"
pivot-label="Renewal date"
pivot-helper-text="Choose the date your policy renews."
></pivot-date>Required (pivot-required)
<pivot-date
pivot-name="required-date"
pivot-label="Start date"
pivot-required
pivot-helper-text="Choose the date your coverage begins."
></pivot-date>Optional (pivot-optional)
<pivot-date
pivot-name="optional-date"
pivot-label="Secondary date"
pivot-optional
pivot-helper-text="This date is optional."
></pivot-date>Disabled (pivot-disabled)
<pivot-date
pivot-name="disabled-date"
pivot-label="Closed date"
pivot-disabled
></pivot-date>Error state (pivot-error + pivot-error-text)
<pivot-date
pivot-name="error-date"
pivot-label="Effective date"
pivot-error
pivot-error-text="Enter a valid effective date."
></pivot-date>Accessible label without a visible label (pivot-aria-label)
Use pivot-aria-label when the surrounding UI already provides the visible
context and a separate field label is not needed.
<pivot-date
pivot-name="unnamed-date"
pivot-aria-label="Date of birth"
></pivot-date>Minimum, maximum, and step constraints (pivot-min, pivot-max, pivot-step)
pivot-min and pivot-max use YYYY-MM-DD date strings. pivot-step is a
number of days; this example permits dates at seven-day intervals starting
from the minimum date.
<pivot-date
pivot-name="appointment-date"
pivot-label="Appointment date"
pivot-min="2026-09-01"
pivot-max="2026-09-30"
pivot-step="7"
pivot-helper-text="Choose a Tuesday in September 2026."
></pivot-date>Combined properties and attributes
This example shows several field properties together: required, an accessible label matching the visible label, an allowed date range, and an error presentation state.
<pivot-date
pivot-name="coverage-date"
pivot-label="Coverage start date"
pivot-aria-label="Coverage start date"
pivot-min="2026-01-01"
pivot-max="2026-12-31"
pivot-step="1"
pivot-required
pivot-error
pivot-error-text="Choose a date between January 1 and December 31, 2026."
></pivot-date>Field label tooltip (pivot-field-label-tooltip)
Use the tooltip for supplemental context. Keep instructions required to
complete the field in pivot-helper-text so they remain visible.
<pivot-date
pivot-name="effective-date"
pivot-label="Effective date"
pivot-helper-text="Select the date this change should take effect."
>
<pivot-field-label-tooltip
slot="field-label-tooltip"
pivot-tooltip-popover-header="About effective dates"
>
<pivot-text>
The effective date determines when the change begins.
</pivot-text>
</pivot-field-label-tooltip>
</pivot-date>Setting properties with JavaScript
The same configuration can be supplied through JavaScript properties. The
pivot-step property is a number, while pivot-min and pivot-max remain
date strings.
<pivot-date id="policy-date"></pivot-date>
<script>
const date = document.querySelector("#policy-date");
date.pivotName = "policy-date";
date.pivotLabel = "Policy date";
date.pivotAriaLabel = "Policy date";
date.pivotMin = "2026-01-01";
date.pivotMax = "2026-12-31";
date.pivotStep = 1;
date.pivotRequired = true;
date.pivotHelperText = "Choose a date in 2026.";
</script>Event: pivot-date-change
pivot-date-change fires on the native date input’s input event with
event.detail.value set to the current value normalized to YYYY-MM-DD (or
an empty string when cleared).
<pivot-date
id="my-date"
pivot-name="effective-date-listener"
pivot-label="Effective date"
></pivot-date>
<script>
document
.getElementById("my-date")
.addEventListener("pivot-date-change", (event) => {
console.log(event.detail.value);
});
</script>Form integration
pivot-date participates in form submission and native constraint
validation.
<pivot-form-container>
<pivot-date
pivot-name="form-date"
pivot-label="Form date"
pivot-required
></pivot-date>
<pivot-button pivot-variant="primary" pivot-type="submit"
>Submit</pivot-button
>
<pivot-button pivot-variant="secondary" pivot-type="reset"
>Reset</pivot-button
>
</pivot-form-container>