Search

Usage

• Use Search to narrow a large set of data by freeform text when typing is faster than scrolling or paging through a list.
• Render the results elsewhere on the page; Search itself only captures the query.
• Use TextField instead when the typed value is data to be saved rather than a query.
• Use Combobox instead when the user selects one matching option as their value.
• Use Filters instead when the user narrows a set by structured criteria built from predefined fields and operators.
• Provide an accessible label (ariaLabel) in place of a visible label when Search sits in a toolbar or page header.
• Provide a visible label (label) when Search sits outside a compact layout.
• Never add a visible label that repeats the placeholder.
• Keep the field editable while results load (isLoading). Never disable the field (isDisabled) during loading.
• Always show what the query returned. Replace empty results with an EmptyState that explains the issue and offers a next step.

Appearance

• Search icon (icon) — defaults to the magnifying glass ("search"). Replace it only when another icon better describes the scope of the search.
• No icon (icon={null}) — remove the icon only when Search sits in a menu or panel narrow enough that the icon crowds the text.
• Small (size="sm") — the default. Use in toolbars, page headers, and filter rows.
• Medium (size="md") — use when Search is the primary control on the page or sits beside medium form controls.
• Default width — capped at space-3200 (256px) to stay compact next to toolbar controls.
• Full width (w="full" with maxW="full") — use when the field ties to full-width content it filters.

Behaviors

• Base, hover, focus, and active states follow standard form-control styling; focus adds the standard 2px focus ring and updates the border color.
• Active state (isActive) — applies the active styling programmatically.
• Disabled state (isDisabled) — blocks interaction and updates the background and text color.
• Loading state (isLoading) — shows a spinner inside the field while results are fetched.
• Critical state (isInvalid with error) — applies critical styling and renders the error message below the field.
• Clear button — appears at the end of the field once it has a value and resets the field and the results.

Content

• Write labels that describe what data is being searched, such as "Search templates". Never label the field with the action alone ("Search").
• Write placeholders in sentence case that name the fields the query matches, such as "Search by name or email". Never end a placeholder with an ellipsis.
• Use description to name what the query matches or explain supported syntax. Write short, complete sentences. Never repeat the placeholder.
• Write errors that say what the field can't handle and what to change about the query. Keep them direct and concise. Never report a failure without a way to resolve it, such as "Invalid search".
• Handle no results with an EmptyState, not an error.

Implementation Notes

• onSearchInput and onSearch are required. onSearchInput receives every value change; onSearch receives the value when a search is triggered.
• onSearch fires only when a trigger prop is set: shouldSearchOnEnter, shouldSearchOnInput, shouldSearchOnBlur, shouldSearchOnClear, or shouldSearchOnDebounce (milliseconds, must be greater than 0). All default to off.
• Search is a controlled field: pass value and update it from onSearchInput.
• The clear button renders automatically whenever onSearchInput is provided — there is no isClearable prop. Clearing calls onClear, then onSearchInput(''), then onSearch('') only when shouldSearchOnClear is set.
• placeholder falls back to ariaLabel when not set. Set placeholder explicitly when the accessible label and hint text differ.
• label, description, and error accept rich content in place of a plain string: React takes a ReactNode; Ember takes the :label, :description, and :error named blocks. Use this for labels with tooltips or icons, and descriptions or errors with inline links.
• elementBefore and elementAfter render custom content inside the input wrapper, forwarded to TextField. In Ember, use the :elementBefore / :elementAfter named blocks.
• The 256px width cap is a max-width on the component; override both w and maxW to go full width.
• Search extends TextField and accepts its remaining form-control props (label, ariaLabel, description, error, isInvalid, isDisabled).
• unsafe_inputWrapperClassName applies classes to the element wrapping the input; wrapperRef (React) and wrapperModifier (Ember) reach that same element.
• Ember invocation is <PlumaSearch> with @argName args. Splattributes land on the input element, so pass container classes through @className. The Ember signature is PlumaSearchSignature.