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-namemaps directly to the nativenameattribute on the input element.- The clear button appears automatically when the input has a value (tracked internally via an
inputlistener) 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-submiton 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 callform.requestSubmit(). - The input has no accessible name when
pivot-aria-labelis omitted or set to an empty string — the input lives in shadow DOM so an external<label for>cannot reach it.pivot-aria-labelis 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 ofpivot-helper-textorpivot-error-texthas a value; when both are unset the region is omitted entirely, and noaria-describedbyis set on the input. See thepivot-field-helper-messagedocumentation for details on its rendering logic. - When both
pivot-error/pivot-error-textandpivot-helper-textare set, error text takes priority and helper text is hidden (delegated topivot-field-helper-message’s own precedence logic). pivot-disabledputs the nativedisabledattribute 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
disabledstate itself, so its restyling depends on attribute reflection.pivotDisabledis declared withoutreflect: true(unlikepivotError, 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 thepivot-disabledhost attribute, so the search button won’t pick up its disabled styling — set thepivot-disabledattribute directly, or reflect the property yourself, when disabling programmatically after initial render and visual state matters.
Accessibility
aria-label— Set frompivot-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>. Settingpivot-aria-label=""removes the attribute entirely, leaving the input with no accessible name.aria-invalid— Always explicitly set on the native<input>:"true"whenpivot-erroris active,"false"otherwise.aria-describedby— Whenpivot-helper-textorpivot-error-textis present, the input is linked viaaria-describedbyto theidrendered onpivot-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 viapivot-field-helper-message’s ownrole="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 staticaria-labels ("Search"and"Clear search"respectively), independent ofpivot-aria-label. Their icons are inline SVGs markedaria-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, butsearchis not one of the field purposes enumerated by the WCAG 1.3.5autocompletetoken list, so noautocompletevalue applies here; this criterion does not add a requirement beyond the label already covered by 4.1.2. pivot-disabledon the buttons — The nativedisabledattribute 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 theTaborder, blocked from activation, and announced as disabled by assistive technology (WCAG 4.1.2) without needing an additionalaria-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. |
Default
<pivot-search-hero
pivot-name="default"
pivot-aria-label="Search"
pivot-placeholder="Search..."
></pivot-search-hero>With Helper Text
<pivot-search-hero
pivot-name="helper"
pivot-aria-label="Search"
pivot-placeholder="Search..."
pivot-helper-text="Enter a keyword, phrase, or product name."
></pivot-search-hero>Error State
<pivot-search-hero
pivot-name="error"
pivot-aria-label="Search"
pivot-placeholder="Search..."
pivot-error
pivot-error-text="No results found. Try a different search term."
></pivot-search-hero>Error State with Helper Text
<!-- When pivot-error is active, pivot-error-text is shown and pivot-helper-text is hidden. -->
<pivot-search-hero
pivot-name="error-helper"
pivot-aria-label="Search"
pivot-placeholder="Search..."
pivot-error
pivot-error-text="No results found. Try a different search term."
pivot-helper-text="Enter a keyword, phrase, or product name."
></pivot-search-hero>Disabled
<pivot-search-hero
pivot-name="disabled"
pivot-aria-label="Search"
pivot-placeholder="Search..."
pivot-disabled
></pivot-search-hero>No Placeholder
<pivot-search-hero
pivot-name="no-placeholder"
pivot-aria-label="Search"
></pivot-search-hero>Custom ID
<pivot-search-hero
pivot-name="custom-id"
pivot-id="my-search-field"
pivot-aria-label="Search"
pivot-placeholder="Search..."
></pivot-search-hero>Event: pivot-search-hero-submit
Clicking the search button dispatches pivot-search-hero-submit with the current
input value in event.detail.value. Type a value below and click the search
button (or open the console) to see it fire — pressing Enter in the
field does not submit, since the component has no keydown handler.
<pivot-search-hero
id="event-search"
pivot-name="event-search"
pivot-aria-label="Search"
pivot-placeholder="Search..."
></pivot-search-hero>
<script>
document
.getElementById("event-search")
.addEventListener("pivot-search-hero-submit", (e) => {
console.log(e.detail.value); // e.g. "wildfire mitigation"
});
</script>