Pivot Docs

    Input

    pivot-input is a single-line text entry web component built on native <input> behavior. It is a form-associated custom element (via ElementInternals), so it participates in form submission, reset, and constraint validation without any extra integration steps.

    It supports common text-like input types, optional helper/error text, required/optional/disabled states, leading/trailing icon slots, and three built-in modifiers:

    • pivot-type="tel" with live formatting: (###) ###-####
    • pivot-masking="ssn" with masked/unmasked toggle
    • pivot-chip to turn committed values into removable chips instead of a single text value

    This guide focuses on implementation and integration details for developers.


    Quick Start

    <pivot-input
    pivot-name="email"
    pivot-label="Work email"
    pivot-type="email"
    pivot-helper-text="Use your @example.com address"
    pivot-required
    >
    </pivot-input>

    Using the icon-leading and icon-trailing slots

    Both slots are optional and independent — use one, both, or neither. Place a FontAwesome <i> element or an inline <svg> in either slot to render an icon at that edge of the input field.

    <pivot-input pivot-name="amount" pivot-label="Loan amount" pivot-type="number">
    <i slot="icon-leading" class="fa-regular fa-dollar"></i>
    <i slot="icon-trailing" class="fa-regular fa-percent"></i>
    </pivot-input>

    Inline SVG elements are also accepted in place of FontAwesome icons:

    <pivot-input pivot-name="search" pivot-label="Search" pivot-type="text">
    <svg slot="icon-leading" viewBox="0 0 640 640" aria-hidden="true">
    <path d="…" />
    </svg>
    </pivot-input>

    FontAwesome icons work in both its web font and SVG+JS modes — in SVG+JS mode, FontAwesome copies the slot attribute onto the <svg> it swaps in, so the icon stays in its slot.

    When a slot has assigned content, the component sets a has-icon-leading or has-icon-trailing attribute on the host and increases the input’s inline padding so the icon and the input text don’t overlap.


    Using the field-label-tooltip slot

    Place a pivot-field-label-tooltip in the field-label-tooltip slot to add an info icon next to the field label. Activating the icon opens a popover with supplemental context for the field.

    <pivot-input pivot-name="routing-number" pivot-label="Routing number">
    <pivot-field-label-tooltip
    slot="field-label-tooltip"
    pivot-tooltip-popover-header="What is a routing number?"
    >

    <pivot-text>
    Your 9-digit routing number is printed at the bottom-left of your personal
    check.
    </pivot-text>
    </pivot-field-label-tooltip>
    </pivot-input>

    Use this slot for supplemental, non-essential context — information that helps some users but isn’t required to complete the field. If the content is critical to task completion, use pivot-helper-text instead, which is always visible and included in the field’s aria-describedby association. See the pivot-field-label-tooltip documentation for full usage guidelines.

    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. The <slot name="field-label-tooltip"> that receives it is rendered directly in pivot-input’s own shadow root by the shared renderFieldLabel() helper (see Implementation Notes), so no forwarding to a separate labeling component is involved.


    Using the input and change events

    pivot-input does not dispatch a custom value-changed event. Instead, the native input and change events fired by the internal <input> are composed: true and bubble across the shadow boundary, so they can be listened for directly on the pivot-input host:

    const emailInput = document.querySelector("pivot-input[pivot-name='email']");

    emailInput.addEventListener("input", (event) => {
    // event.target is retargeted to the pivot-input host itself (not the
    // internal <input>) because the event originates inside shadow DOM.
    const value = event.target.shadowRoot?.querySelector(
    "input[data-element='field']",
    )?.value;
    console.log(value);
    });

    For pivot-type="tel" and pivot-masking="ssn", the displayed value is reformatted on blur (see Implementation Notes), so an input listener sees the raw in-progress value while the field is focused, not the final formatted/masked string. For form submission, prefer reading the value through the standard FormData flow (see Form Association) rather than wiring up manual input/change listeners.


    CSS Parts

    Name Description
    container The outer grid container wrapping the label, input, and message regions

    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>, so browser constraint validation applies (required, pattern, maxlength, etc.).
    • Helper and error text rendering is delegated to pivot-field-helper-message. The message region is only rendered when at least one of pivot-helper-text or pivot-error-text has a value; when both are unset the region is omitted entirely. See the pivot-field-helper-message documentation for details on its rendering logic.
    • 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-input calls directly from its own render() method. This is a plain function, not a separate custom element: the label markup it returns is part of pivot-input’s own shadow root, styled by field-label.css merged into pivot-input’s static styles. The same helper is shared by pivot-checkbox, pivot-radio, pivot-date, pivot-text-area, and pivot-selector.
    • pivot-helper-text is rendered below the field when provided, unless an error message is being shown. Error text — either pivot-error-text or the browser’s native validation message (see Validation and Error Handling) — takes priority, and helper text is hidden while it is displayed.
    • When pivot-optional is set, an (optional) badge is rendered inline next to the label.
    • When pivot-required is set, a * indicator is rendered inline next to the label.
    • Password and SSN modes render a separate toggle button for show/hide behavior.
    • When pivot-chip is set, pressing Enter with a nonblank value creates a removable pivot-chip below the field and clears the native input. On form submission, each chip is included as a separate entry under pivot-name.

    Form Association

    pivot-input sets static formAssociated = true, making it a form-associated custom element that integrates with ElementInternals internally. This means:

    • Its value is included in FormData when the parent form is submitted, using pivot-name as the key.
    • pivot-input 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.
    • Form reset automatically restores the field to its empty initial state via formResetCallback, including clearing any chips added in pivot-chip mode and any native validation message currently displayed.
    • When a parent <fieldset> or form is disabled, the component disables itself via formDisabledCallback.

    name attribute

    Internally, the component mirrors pivot-name to the host element’s native name attribute on each update. This is required by the form-associated custom elements spec for the browser to use the correct key when building FormData. Do not manually set a name attribute on the host element — it will be overwritten.

    SSN submission value

    For pivot-masking="ssn", the value submitted to the form is the raw 9-digit string (e.g. "123456789"), not the formatted (123 45 6789) or masked (••• •• ••••) display value.

    Chip submission values

    When pivot-chip is enabled, the component submits each chip as a separate FormData entry using pivot-name as the key. For example, chips labelled Alice and Bob in an input with pivot-name="guests" produce:

    guests=Alice
    guests=Bob

    Use formData.getAll("guests") to retrieve all submitted values. When no chips have been added, the component contributes no value to the form submission. Resetting the parent form (native reset, or calling form.reset()) clears all chips via formResetCallback.


    Methods

    checkValidity()

    Returns boolean. Checks the current constraint-validation state of the native input (kept in sync with ElementInternals after every update) and returns whether it is currently valid. When the field is invalid, the browser fires an invalid event on the host, which pivot-input handles by rendering the native validation message inline in Pivot’s error styling — see Validation and Error Handling.

    const input = document.querySelector("pivot-input[pivot-name='email']");
    input.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 input = document.querySelector("pivot-input[pivot-name='email']");
    input.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.


    Validation and Error Handling

    Native validation messages

    pivot-input 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 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:

    • the containing form is submitted while the field is invalid (submission is still blocked),
    • form.checkValidity() / form.reportValidity() is called, or
    • the element’s own checkValidity() / reportValidity() is called.
    <form>
    <pivot-input
    pivot-name="email"
    pivot-label="Work email"
    pivot-type="email"
    pivot-required
    >
    </pivot-input>
    <button type="submit">Submit</button>
    </form>
    <!-- Submitting empty renders the browser's "Please fill out this field."
    message below the input in Pivot error styling. -->

    The message is captured at the moment the invalid event fires. It is removed as soon as the field becomes valid again (for example, while the user types a valid value), 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.

    The browser does not move focus to a field whose invalid event is cancelled, so submitting a form with invalid pivot-input fields does not automatically focus the first invalid one — see Focus Management.

    Error state precedence

    The field is in its error state — error styling, aria-invalid="true", and a has-error attribute on the host — when any of the following is true:

    • pivot-error is set,
    • pivot-error-text has a value, or
    • a native validation message is currently 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 an error message, and any pivot-helper-text stays visible.

    The component manages has-error itself; don’t set or remove it manually. Use pivot-error / pivot-error-text to control the error state from your own code.

    Constraints

    • 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.
    • Built-in patterns:
      • tel: \([0-9]{3}\) [0-9]{3}-[0-9]{4}
      • url: https?://.+
      • visible ssn: [0-9]{3} [0-9]{2} [0-9]{4}
    • Max lengths (applied to raw digit input while the field is focused):
      • tel: 10 (displayed as a 14-character formatted string after blur)
      • ssn: 9 (displayed as a formatted or masked string after blur)

    Recommended integration pattern:

    1. Use pivot-required, pivot-type, and built-in pattern constraints for first-pass validation — their native messages render automatically on submit.
    2. Set pivot-error-text when you need more specific, actionable copy than the browser’s default message, or to surface server-side errors.
    3. Validate again server-side.

    Accessibility

    pivot-input leans on native <label>/<input>/<button> semantics rather than custom ARIA roles.

    • Accessible name — pivot-input renders the field label with the shared renderFieldLabel() helper directly into its own shadow root, so the resulting <label for="..."> and the native <input id="..."> live in the same shadow root and do have a working native for/id association whenever pivot-label is set (see Focus Management for the click-to-focus behavior this enables). On top of that native association, the native <input>'s accessible name is also set explicitly via aria-label: pivot-aria-label if provided, otherwise it falls back to the visible pivot-label text automatically (WCAG 4.1.2). Because an explicit aria-label takes precedence over an associated <label> in accessible-name computation, this guarantees a correct accessible name even in the one case where no <label> element is rendered at all — when pivot-label is omitted (e.g. pivot-input embedded inside pivot-radio or pivot-checkbox) — so in the common case (a visible pivot-label), you don’t need to set pivot-aria-label at all.
      • Set pivot-aria-label when you need the accessible name to differ from the visible label — most commonly when pivot-label is omitted entirely (e.g. when pivot-input is embedded inside pivot-radio or pivot-checkbox) and there is no visible text to fall back to.
      • pivot-aria-label is applied unconditionally whenever it has a value, taking precedence over the pivot-label fallback. Avoid setting pivot-aria-label to different text than pivot-label when both are visible/present, since that produces a mismatch between the visible label and the accessible name (WCAG 2.5.3, Label in Name).
    • aria-invalid — set to "true" on the native <input> whenever the field is in its error state (pivot-error, pivot-error-text, or a displayed native validation message — see Error state precedence), and "false" otherwise (WCAG 4.1.2).
    • aria-describedby — when pivot-helper-text, pivot-error-text, or a native validation message is present, the native input is linked to pivot-field-helper-message via aria-describedby, so assistive technology announces the helper or error message when the field receives focus (WCAG 1.3.1, 4.1.3). The error text is additionally announced immediately via pivot-field-helper-message’s own role="alert", not only when the field regains focus — see that component’s README.
    • Native input types — pivot-type maps directly to the native type attribute (email, number, password, search, tel, url, date, text), preserving each type’s built-in semantics, virtual keyboard, and OS-level affordances.
    • Input purpose (WCAG 1.3.5) — the component does not expose a pivot-autocomplete property or otherwise set autocomplete on the internal <input>. For fields that collect common user information (email, name, address, etc.), there is currently no way to satisfy WCAG 1.3.5 (Identify Input Purpose) through this component alone.
    • Placeholder vs. label — pivot-placeholder (and the built-in tel/ssn format hints) is not a substitute for pivot-label. Placeholder text disappears on input and is not reliably announced by all screen readers; always provide a real label.
    • The show/hide toggle (rendered for pivot-type="password" and pivot-masking="ssn") is a native <button> with aria-label of "Show" or "Hide" depending on the current visibility state.

    Screen Reader Behavior

    • Screen readers announce the input using its aria-label — either pivot-aria-label when set, or the pivot-label text as an automatic fallback (see precedence note above). The explicit aria-label is the source of the accessible name even though a native <label for> association is also in effect, because aria-label takes precedence in accessible-name computation.
    • Helper or error text — including a native validation message rendered after a failed submit — is automatically associated as a description via aria-describedby and announced when the field receives focus. Because error messages render with role="alert", a native validation message is also announced as soon as it appears.
    • The show/hide toggle is announced as a button labeled Show or Hide.
    • aria-errormessage is not set by the component. If your form system needs it, set it externally by querying the internal input and managing the attribute during validation.

    Keyboard Navigation

    The component relies entirely on native input and button keyboard behavior; it does not attach any custom key handlers for navigation.

    • Tab moves focus to the input, then to the optional show/hide toggle button.
    • Standard native text-editing and caret-navigation keys work as expected in the input.
    • For pivot-type="tel", raw digits are accepted while the field is focused (max 10 characters); the value is formatted to (###) ###-#### on blur, and reformatted back to raw digits on re-focus for editing.
    • For pivot-masking="ssn", raw digits are accepted while the field is focused (max 9 characters); on blur the value is displayed as masked (••• •• ••••) or formatted (### ## ####) depending on the current show/hide toggle state.
    • When pivot-chip is set, pressing Enter with a nonblank value adds a chip, clears the input, and keeps focus on the input, instead of submitting the containing form. Each chip’s remove button is a native <button> — pivot-chip attaches no keyboard handlers of its own — so Enter and Space activate it per standard button semantics, dispatching pivot-chip-remove, which pivot-input handles by removing that chip. See the pivot-chip documentation for details.

    Focus Management

    • The component does not auto-focus by default.

    • When form submission or reportValidity() fails, focus is not moved to the invalid 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".

    • Because the field label and the native <input> are both rendered into pivot-input’s own shadow root by the shared renderFieldLabel() helper, clicking or tapping the visible label text (when pivot-label is set) natively focuses the input via the browser’s built-in <label for> behavior — no extra wiring is required.

    • pivot-input extends PivotBase, which sets delegatesFocus: true on the shadow root. This means calling .focus() directly on the pivot-input host — with no need to reach into shadowRoot — delegates focus to the first focusable element inside its shadow tree (the native <input>), and :focus-visible/:focus-within-style styling on the host reflects focus of any element inside:

      document.querySelector("pivot-input[pivot-name='email']").focus();
    • Because a unique internal input id is generated per component instance using a random suffix (when pivot-id is not provided), avoid writing tests or external <label for> references that depend on a specific generated id value — use pivot-id if you need a stable, predictable id.

    • Chip removal focus: After a chip is removed, focus moves to the next remaining chip’s remove button, or the previous chip when the last chip was removed. When no chips remain, focus returns to the text field so keyboard and screen reader users can continue entering values.


    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 input. The input's `aria-label` falls back to the visible `pivotLabel` text automatically when this is unset, so this only needs to be set to override that text — most commonly when `pivotLabel` is omitted entirely (e.g. because `pivot-input` is embedded inside `pivot-radio` or `pivot-checkbox`) and there is no visible label text to fall back to.
    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-placeholder string | null null This will create an attribute: pivot-placeholder="value"
    pivot-type "date" | "email"| "number" | "password" | "search" | "tel" | "text" | "url" "text" This will create an attribute: pivot-type="value"
    pivot-masking "ssn" | null null Optional masking mode for the input 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>
    pivot-chip boolean false Enables chip creation when the user presses Enter in the input.

    Slots

    Name Description
    icon-leading Icon at the leading edge (left) of the input. Accepts an inline `<svg>` or a FontAwesome `<i>` element.
    icon-trailing Icon at the trailing edge (right) of the input. Accepts an inline `<svg>` or a FontAwesome `<i>` element.
    field-label-tooltip Accepts a single `pivot-field-label-tooltip` element rendered inline with the field label.

    CSS Custom Properties

    Name Description
    --component-field-gap Gap between the label row, input row, helper message, and chip bag within the outer grid container.
    --component-field-chip-bag-gap Gap between chips in the chip bag.
    --component-field-label-gap Gap between the label text, the optional/required indicator, and the field-label-tooltip icon within the label row.
    --typography-constants-body-family Font family of the label text and the "(optional)" indicator text.
    --component-field-label-color Text color of the label.
    --global-color-text-on-light-light-color Text color of the "(optional)" indicator.
    --global-color-text-on-light-error-color Text color of the required `*` indicator.
    --global-interaction-md Minimum block size of the input element.
    --component-field-control-general-inset-y Vertical padding of the input; also used to position leading and trailing slot icons.
    --component-field-control-general-inset-x Horizontal padding of the input; also used to position leading and trailing slot icons and to reserve inline space for them.
    --typography-body-md-size Font size of the input text.
    --typography-body-md-height Line height of the input text.
    --component-field-control-input Text color of the input value.
    --component-field-control-surface Background color of the input and the show/hide visibility toggle button.
    --component-field-control-border-color Border color of the input in the default state.
    --component-field-control-border-width Border width of the input, applied in both the default and error states.
    --component-field-control-general-radius Border radius of the input.
    --component-field-control-surface-disabled Background and border color when the input is disabled.
    --component-field-control-input-placeholder Placeholder text color.
    --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.
    --typography-icon-md-size Size of the show/hide toggle icon and the leading/trailing slot icons.
    --global-color-icons-font-awesome-default-color Color of the show/hide toggle icon and the leading/trailing slot icons.