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, andpivot-search-heroto 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:
- Error message — when
pivot-erroris set andpivot-error-textis provided: a warning icon followed by the error text. - Helper message — when
pivot-helper-textis provided andpivot-erroris not set (orpivot-error-textis empty): the helper text only. - 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-errormust be present andpivot-error-textmust be non-null for the error state to render. Settingpivot-erroralone (withoutpivot-error-text) produces no output.pivot-helper-textis only rendered whenpivot-erroris absent,false, orpivot-error-textis 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-rooton 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:
- Generate a stable helper id (typically
`${pivotName}-helper`or`${pivotName}-${uniqueID}-helper`, whereuniqueIDcomes fromnanoid). - Set that id as the
idattribute on<pivot-field-helper-message>. - Set
aria-describedbyon the native input/textarea to that same id, but only whenpivotHelperTextorpivotErrorTextis 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 (
errorIconinconstants.ts) is an inline SVG markedaria-hidden="true"(andfocusable="false"), consistent with other decorative icons in this library (e.g. the icons inpivot-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-textintentionally does not get a role — it’s static description content, not a status message, so it’s only exposed viaaria-describedbyon focus, same as before.- Caveat: if
pivot-error/pivot-error-textare 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 viaaria-describedbyon 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-messagebelow its native<input>. - Text Area — composes
pivot-field-helper-messagebelow its native<textarea>. - Date — composes
pivot-field-helper-messagebelow its native date input. - Radio — composes
pivot-field-helper-messagebelow the radio option group. - Checkbox — composes
pivot-field-helper-messagebelow the checkbox option group. - Search Hero — composes
pivot-field-helper-messagebelow 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. |
pivot-field-helper-message is not a standalone component — in real usage it must always be paired with the form control it describes, with its id referenced by that control’s aria-describedby (composed internally by pivot-input, pivot-checkbox, pivot-date, pivot-radio, pivot-text-area, and pivot-search-hero, or wired up by hand when building a custom form control — see its README). The demos below render it in isolation, with no paired field, to focus on its own helper/error rendering.
Helper text (pivot-helper-text)
<pivot-field-helper-message
pivot-helper-text="We'll only use this to send account notifications"
></pivot-field-helper-message>Error state (pivot-error, pivot-error-text)
Setting pivot-error together with pivot-error-text renders the error text with a leading warning icon in place of any helper text.
<pivot-field-helper-message
pivot-error
pivot-error-text="Enter a valid email address"
></pivot-field-helper-message>Error text takes priority over helper text
When both pivot-helper-text and pivot-error-text are set and pivot-error is active, only the error message renders — the helper text has no visible fallback while an error is showing.
<pivot-field-helper-message
pivot-error
pivot-error-text="Enter a valid email address"
pivot-helper-text="We'll only use this to send account notifications"
></pivot-field-helper-message>