Pivot Docs

    Field Helper Message

    pivot-field-helper-message is a display utility component that renders contextual text below a form field. It shows either helper text (a persistent hint) or error text accompanied by a warning icon, depending on the active state. When neither state is active, it renders nothing.

    This component must only be used within a supported form component. It is not a standalone component. Never place it on a page with no associated form control. It is embedded in pivot-input, pivot-text-area, pivot-date, pivot-radio, pivot-checkbox, and pivot-search-hero to handle the helper/error message region; use it by hand only when building a custom form control that needs the same helper/error rendering (see Using this component with a form field below). See Related Components for the full list.


    Quick Start

    <!-- Helper text (default state) -->
    <pivot-field-helper-message
    pivot-helper-text="Use your @example.com address"
    >
    </pivot-field-helper-message>

    <!-- Error state -->
    <pivot-field-helper-message
    pivot-error
    pivot-error-text="Please enter a valid email address"
    >
    </pivot-field-helper-message>

    The component renders one of three outputs:

    1. Error message — when pivot-error is set and pivot-error-text is provided: a warning icon followed by the error text.
    2. Helper message — when pivot-helper-text is provided and pivot-error is not set (or pivot-error-text is empty): the helper text only.
    3. Nothing — when neither condition is met.

    Error state takes full priority: if both pivot-helper-text and pivot-error-text are set and pivot-error is active, only the error text is shown — helper text has no visible fallback while an error is active.


    Implementation Notes

    • pivot-error must be present and pivot-error-text must be non-null for the error state to render. Setting pivot-error alone (without pivot-error-text) produces no output.
    • pivot-helper-text is only rendered when pivot-error is absent, false, or pivot-error-text is empty. When the error state becomes active, helper text is hidden entirely — there is no visible fallback.
    • The error icon is an inline SVG (Font Awesome warning triangle) defined in constants.ts. Its color and size are driven by design tokens (see below) and cannot be changed independently of them.
    • The component uses display: flow-root on the host, which prevents margin collapse with adjacent elements and ensures the message participates in the block layout correctly.

    Using this component with a form field

    pivot-field-helper-message does not manage its own id or its association with a form control — the parent component is responsible for both. The convention used across pivot-input, pivot-date, pivot-text-area, pivot-radio, pivot-checkbox, and pivot-search-hero is:

    1. Generate a stable helper id (typically `${pivotName}-helper` or `${pivotName}-${uniqueID}-helper`, where uniqueID comes from nanoid).
    2. Set that id as the id attribute on <pivot-field-helper-message>.
    3. Set aria-describedby on the native input/textarea to that same id, but only when pivotHelperText or pivotErrorText is truthy — so the attribute is never present pointing at an empty/unrendered message.
    <div class="field-wrapper">
    <label for="email">Email address</label>
    <input
    id="email"
    type="email"
    aria-invalid="false"
    aria-describedby="email-helper"
    />

    <pivot-field-helper-message
    id="email-helper"
    pivot-helper-text="We'll only use this to send account notifications"
    >
    </pivot-field-helper-message>
    </div>

    Switch to the error state on validation failure:

    const helper = document.querySelector("pivot-field-helper-message");
    const input = document.querySelector("input#email");

    helper.pivotErrorText = "Enter a valid email address";
    helper.pivotError = true;
    input.setAttribute("aria-invalid", "true");

    Reset back to the helper state:

    helper.pivotError = false;
    input.removeAttribute("aria-invalid");

    If you are building a custom form field, prefer composing an existing field component (pivot-input, pivot-text-area, pivot-date, pivot-radio, pivot-checkbox) over wiring pivot-field-helper-message up by hand — those components already implement the id-generation and aria-describedby timing shown above.


    Accessibility

    ARIA and Semantics

    pivot-field-helper-message renders plain text inside a <span class="pivot-input-helper-text"> (with the error icon prepended in the error state). The helper-text span has no implicit ARIA role of its own and sets no role or aria-* attributes. The error-state span additionally carries role="alert" (WCAG 4.1.3, Status Messages) — see Screen Reader Behavior below.

    • The component does not assign its own id. Association with a form control is entirely the responsibility of the parent — see Using this component with a form field above.
    • The error icon (errorIcon in constants.ts) is an inline SVG marked aria-hidden="true" (and focusable="false"), consistent with other decorative icons in this library (e.g. the icons in pivot-search-hero’s constants). It contributes no redundant text to the accessibility tree — the adjacent error text is what carries the meaning.

    Screen Reader Behavior

    Because the message text lives inside the description referenced by the field’s aria-describedby, it is announced when the field receives focus (WCAG 4.1.2 Name, Role, Value) — this covers the common case where a user tabs into a field that already has helper or error text.

    Status messages (WCAG 4.1.3): the error-state span is rendered with role="alert", which has an implicit aria-live="assertive" and aria-atomic="true". Because the error and helper states render as different template branches, switching pivotError/pivotErrorText on inserts a brand-new role="alert" node into the DOM rather than mutating an existing one — the insertion pattern most screen readers reliably pick up as a live-region announcement. This means validation errors are announced as soon as they become active, even if the associated field already has focus and is never re-focused, without requiring the parent to wire up a separate live region.

    • pivot-helper-text intentionally does not get a role — it’s static description content, not a status message, so it’s only exposed via aria-describedby on focus, same as before.
    • Caveat: if pivot-error/pivot-error-text are already active on the component’s first render (e.g. server-rendered or pre-set validation state, with no prior helper/nothing state to transition from), some screen readers won’t treat that as a live-region insertion, since there is no preceding DOM state to diff against — the error text is still exposed via aria-describedby on focus in that case, but may not be announced proactively. If you need errors announced on initial load in that scenario, move focus to the field (or its message) after render.

    Keyboard Navigation

    None. The component renders no focusable or interactive elements and attaches no key handlers.

    Focus Management

    None. The component never calls .focus()/.blur(), sets no tabindex, and does not participate in a focus-trap. PivotBase’s delegatesFocus: true shadow root option has no effect here since there is nothing focusable inside the shadow tree to delegate to.


    Related Components

    • Field Label Tooltip — optional tooltip content slotted into pivot-field-label, for supplemental (non-error, non-required) field context.
    • Input — composes pivot-field-helper-message below its native <input>.
    • Text Area — composes pivot-field-helper-message below its native <textarea>.
    • Date — composes pivot-field-helper-message below its native date input.
    • Radio — composes pivot-field-helper-message below the radio option group.
    • Checkbox — composes pivot-field-helper-message below the checkbox option group.
    • Search Hero — composes pivot-field-helper-message below its search input.

    References


    API Reference

    Props

    Name Type Default Description
    pivot-helper-text string | null null Supplemental text rendered below the field. Hidden when `pivot-error` is active and `pivot-error-text` is non-empty.
    pivot-error-text string | null null Error message rendered with an error icon. Only displayed when `pivot-error` is also set.
    pivot-error boolean false Activates error state. Requires `pivot-error-text` to display the error message and icon.

    CSS Custom Properties

    Name Description
    --component-field-helper-gap Gap between the error icon and the message text.
    --global-color-text-on-light-error-color Error message text color.
    --global-color-icons-font-awesome-danger-color Error icon color.
    --typography-icon-sm-size Error icon inline and block size.