Pivot Docs

    Search Hero

    pivot-search-hero is a prominent search input component that renders a native <input type="search"> with an integrated search button and an inline clear button that appears automatically when the field has a value.


    Quick Start

    <pivot-search-hero
    pivot-name="site-search"
    pivot-aria-label="Search the site"
    pivot-placeholder="Search..."
    >
    </pivot-search-hero>

    Using the pivot-search-hero-submit event

    pivot-search-hero does not submit a parent <form> on its own — the search button lives in shadow DOM, so a shadow-DOM button click cannot trigger light-DOM form submission. Instead, clicking the search button dispatches a pivot-search-hero-submit CustomEvent (bubbling, composed) whose detail.value is the current input value at the moment of the click:

    document
    .querySelector("pivot-search-hero")
    .addEventListener("pivot-search-hero-submit", (event) => {
    fetch(`/search?q=${encodeURIComponent(event.detail.value)}`);
    });

    For form-based usage, listen for the event and call form.requestSubmit() manually:

    <form id="search-form" action="/search" method="get">
    <pivot-search-hero
    pivot-name="q"
    pivot-aria-label="Search"
    >
    </pivot-search-hero>
    </form>

    <script>
    const form = document.getElementById("search-form");
    document
    .querySelector("pivot-search-hero")
    .addEventListener("pivot-search-hero-submit", () => form.requestSubmit());
    </script>

    This event fires when the search button is activated or Enter is pressed inside the field — see Keyboard Navigation.


    CSS Parts

    Part Description
    container The outer wrapper element surrounding the input, buttons, and helper message.

    Implementation Notes

    • pivot-name maps directly to the native name attribute on the input element.
    • The clear button appears automatically when the input has a value (tracked internally via an input listener) and is removed from the DOM entirely when the field is empty, rather than merely hidden. Clicking it clears the field and returns focus to the input.
    • The search button fires pivot-search-hero-submit on click and does not submit a parent form directly (shadow DOM buttons cannot trigger light-DOM form submission). For form-based usage, listen for the event and call form.requestSubmit().
    • The input has no accessible name when pivot-aria-label is omitted or set to an empty string — the input lives in shadow DOM so an external <label for> cannot reach it. pivot-aria-label is required for WCAG 4.1.2 compliance when no visible label is present. It defaults to "Search", so an accessible name is present out of the box unless explicitly cleared.
    • 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, and no aria-describedby is set on the input. See the pivot-field-helper-message documentation for details on its rendering logic.
    • When both pivot-error/pivot-error-text and pivot-helper-text are set, error text takes priority and helper text is hidden (delegated to pivot-field-helper-message’s own precedence logic).
    • pivot-disabled puts the native disabled attribute on the <input>, the search button, and the clear button (when present) — all three are natively disabled together.
    • The search button’s selector targets the host attribute rather than the disabled state itself, so its restyling depends on attribute reflection. pivotDisabled is declared without reflect: true (unlike pivotError, which does reflect), so toggling the property from JavaScript alone (e.g. el.pivotDisabled = true) natively disables the input, search button, and clear button (since each ?disabled= binding reads the property directly) but will not add the pivot-disabled host attribute, so the search button won’t pick up its disabled styling — set the pivot-disabled attribute directly, or reflect the property yourself, when disabling programmatically after initial render and visual state matters.

    Accessibility

    • aria-label — Set from pivot-aria-label (default "Search") on the native <input>. Required for WCAG 4.1.2 when no visible label is present, since the input lives in shadow DOM and cannot be labelled via an external <label for>. Setting pivot-aria-label="" removes the attribute entirely, leaving the input with no accessible name.
    • aria-invalid — Always explicitly set on the native <input>: "true" when pivot-error is active, "false" otherwise.
    • aria-describedby — When pivot-helper-text or pivot-error-text is present, the input is linked via aria-describedby to the id rendered on pivot-field-helper-message. Assistive technology announces the helper or error message when the field receives focus. The attribute is omitted entirely (not merely empty) when neither helper nor error text is set. 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.
    • Search and clear buttons — Both are native <button type="button"> elements with static aria-labels ("Search" and "Clear search" respectively), independent of pivot-aria-label. Their icons are inline SVGs marked aria-hidden="true", so they contribute no redundant text to the accessible name.
    • Input purpose (WCAG 1.3.5) — type="search" communicates the field’s role to browsers and some assistive technology, but search is not one of the field purposes enumerated by the WCAG 1.3.5 autocomplete token list, so no autocomplete value applies here; this criterion does not add a requirement beyond the label already covered by 4.1.2.
    • pivot-disabled on the buttons — The native disabled attribute is applied to the search button and the clear button (when present) exactly as it is to the input, so all three are removed from the Tab order, blocked from activation, and announced as disabled by assistive technology (WCAG 4.1.2) without needing an additional aria-disabled.

    Screen Reader Behavior

    The component exposes a single labelled searchbox-role input (native <input type="search">), a Search button, and — conditionally — a Clear search button and a describing helper/error message. Screen readers announce the input’s accessible name on focus, then the helper/error message (via aria-describedby) if one is present, and announce aria-invalid="true" when pivot-error is set. The container <div part="container"> itself carries no role and is not announced. When pivot-disabled is set, the disabled state is announced for the input, the search button, and the clear button alike — native disabled suppresses each from the tab order and screen readers report them as dimmed/unavailable.

    Keyboard Navigation

    pivot-search-hero listens for keydown on the native input to submit on Enter; the rest of its keyboard behavior comes from the native elements it renders:

    Key Effect
    Tab / Shift+Tab Moves focus between the input, the clear button (when present), and the search button.
    Typing Updates the input value and toggles the clear button’s presence via the native input event.
    Enter (in the input) Dispatches pivot-search-hero-submit with the input’s current value, via a keydown listener on the field.
    Enter / Space (on a button) Activates the focused button — clears the field (and returns focus to the input) or fires pivot-search-hero-submit.

    Note: when pivot-disabled is set, the input, the search button, and the clear button (when present) are all natively disabled and removed from the Tab order — none can be reached or activated by keyboard, and the input’s Enter-to-submit keydown listener never fires.

    Focus Management

    pivot-search-hero does not trap focus, but its host (PivotBase) enables delegatesFocus on the shadow root, so focus and :focus-visible styling on the host reach the first focusable element inside. handleClear explicitly calls .focus() on the native input after clearing its value, returning focus to the field rather than leaving it on the (now-removed) clear button.


    Related Components

    • Field Helper Message — renders the helper/error text below the input and determines error-vs-helper precedence; see its README for full rendering and accessibility details.

    API Reference

    Props

    Name Type Default Description
    pivot-aria-label string "Search" Sets `aria-label` on the native `<input>`. Required for WCAG 4.1.2 compliance when no visible label is present — external `<label for>` cannot cross the shadow DOM boundary to reach the inner input.
    pivot-helper-text string | null null Supplemental copy rendered below the input. Hidden when the error state is active.
    pivot-error-text string | null null Error copy rendered below the input when `pivot-error` is set. Replaces `pivot-helper-text` while active.
    pivot-name string "" Forwarded as the `name` attribute on the native input.
    pivot-id string "" When provided, used as the input's `id`. When omitted, a unique `id` is generated from `pivot-name`.
    pivot-placeholder string | null null Placeholder text shown inside the input when empty. Not a substitute for an accessible label.
    pivot-error boolean false Activates error styling on the input. Reflects to the host attribute so CSS selectors respond reactively.
    pivot-disabled boolean false Disables the input and search button. Maps to native `disabled`.

    Events

    Name Type Description
    pivot-search-hero-submit CustomEvent Fired when the search button is clicked, with the current input value in `detail.value`.

    CSS Custom Properties

    Name Description
    --component-field-gap Gap between the input and the helper/error message region within the container.
    --global-interaction-md Minimum block size of the input, and the inline/block size of the clear and search buttons.
    --component-field-control-general-inset-y Vertical padding of the input.
    --component-field-control-general-inset-x Horizontal padding of the input; also used to position the clear button relative to the search button.
    --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 in the default state.
    --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, and of the search button's outer corners.
    --component-field-control-surface-disabled Background and border color of the input when `pivot-disabled` is set.
    --component-field-control-input-placeholder Placeholder text color.
    --component-field-control-surface-error Background color of the input when `pivot-error` is set.
    --component-field-control-border-color-error Border color of the input when `pivot-error` is set.
    --typography-icon-md-height Size (height and width) of the clear and search button icons.
    --global-color-icons-font-awesome-default-color Icon color of the clear button.
    --global-color-icons-font-awesome-inverse-color Icon color of the search button.
    --global-color-icons-font-awesome-disabled-color Icon color of the search button when `pivot-disabled` is set.
    --component-button-primary-default-surface Background color of the search button.
    --component-button-primary-disabled-surface Background color of the search button when `pivot-disabled` is set.