Pivot Docs

    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 FormData using pivot-name as the key.
    • pivot-date defines its own checkValidity() / 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 to ElementInternals after 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, formDisabledCallback updates 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 | false

    reportValidity()

    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 invalid

    Both 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-name is required. The component throws at update time when pivot-name is 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, and pivot-step are forwarded to the native date input. Use valid date strings in YYYY-MM-DD format for pivot-min and pivot-max. pivot-step is a positive number expressed in days. The component does not support the native any keyword for step.
    • 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), which pivot-date calls directly from its own render() method.
    • Helper and error message rendering is delegated to pivot-field-helper-message. Error text — pivot-error-text or the browser’s native validation message — takes priority over helper text while it is shown.
    • pivot-date is a form-associated custom element. It participates in form submission, reset, and validation through ElementInternals and works inside pivot-form-container without 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


    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.