rc-search-bar
Search field/view wrapper for a native <input type="search"> with icon chrome, clear button, suggestions, and debounced events.
- Package
@rcarls/rc-search-bar- Element
<rc-search-bar>- Native dependency
- Requires a direct child native search input
- State model
- Controlled or uncontrolled search value and search view
- Main events
rc-search-bar-inputrc-search-bar-clearrc-search-bar-togglerc-search-bar-suggestion-select- Related
- Usage rulesTheme previews
Installation
- npm
- Yarn
- pnpm
npm install @rcarls/rc-webcomponents@next
yarn add @rcarls/rc-webcomponents@next
pnpm add @rcarls/rc-webcomponents@next
import '@rcarls/rc-webcomponents/rc-search-bar/define';
Usage
Wrap a native <input type="search"> and label it. Wrap the bar in <search> when it is the
page's search landmark.
<search>
<label for="q" class="visually-hidden">Search recipes</label>
<rc-search-bar placeholder="Search 51 recipes">
<span slot="leading" aria-hidden="true">🔍</span>
<input type="search" id="q" name="q" />
</rc-search-bar>
</search>
Live demo
Accessibility
The component writes no ARIA to the input: type="search" already exposes the searchbox role,
and author labels are never overwritten. It adds no landmark of its own. The clear button is a
real <button> named by the translatable clear message, and activating it returns
focus to the input before the button hides. In a search view (variant="view"), Escape in the
input closes the open view.
Theming
The default demo mode shows the component without a package theme. Use the shared preview controls on this page to compare inherited, light, and dark color schemes or to apply the optional Material theme only inside the demo frames.
Search view
Set variant="view" to enable the expandable search view. The component keeps
the direct child <input type="search"> as the value, label, and form source of
truth, while open / default-open control the view panel.
Use the suggestions slot for rich Material-style rows. For simple text
suggestions, the component can read the native input's list attribute and
render the associated <datalist><option> values when the slot is empty.
<datalist> remains a progressive enhancement path: browser styling,
high-contrast behavior, and screen-reader announcement vary, so slotted
suggestions are recommended when you need rich rows or tighter accessibility
control.
<rc-search-bar variant="view">
<input type="search" aria-label="Search recipes" list="recipe-suggestions" />
<datalist id="recipe-suggestions">
<option value="pasta" label="Pasta"></option>
<option value="tomato soup"></option>
</datalist>
</rc-search-bar>
Localization
Built-in text follows the element's own lang, else <html lang>. Override it with
messages, or register it for every instance under rc-search-bar: clear. See
Localization.
API
Properties
| Property | Markup | Type | Default | Description |
|---|---|---|---|---|
messages | JS property only | Partial<RCSearchBarMessages> | undefined | Not specified | Built-in text overrides; unset keys fall back to registered text, then English. |
variant | variant | RCSearchBarVariant | 'bar' | Presentation mode: docked search bar or expandable search view. |
debounce | debounce | number | 200 | Debounce window in ms for `rc-search-bar-input`; `0` dispatches synchronously. |
allowNativeClear | allow-native-clear | boolean | false | When set, leaves the browser's native WebKit cancel button visible. |
showClearOnFocus | show-clear-on-focus | boolean | false | When set, the clear button is visible whenever the input is focused. Matching the Apple HIG "cancel" pattern. Consider setting `messages.clear` to `Cancel` in this mode. |
disabled | disabled | boolean | Not specified | Disables the component and mirrors the state to the slotted input. |
placeholder | placeholder | string | undefined | Not specified | Placeholder mirrored onto the native input. Consumer `placeholder` attribute is always honored. |
open | open | boolean | Not specified | Whether the search view panel is open. Host writes are silent. |
defaultOpen | default-open | boolean | Not specified | Initial uncontrolled search view open state. |
value | JS property only | string | Not specified | The current search value. Reads from the native input when present. Host writes are silent (no events) and win over slotted author values. |
defaultValue | default-value | string | undefined | Not specified | Initial uncontrolled value hint. Applied once, and only when neither an author `value`, a host `value` write, nor user input owns the value. |
Methods
| Method | Description |
|---|---|
showView() | Opens the search view and fires `rc-search-bar-toggle` when it changes. |
closeView() | Closes the search view and fires `rc-search-bar-toggle` when it changes. |
toggleView() | Toggles the search view and fires `rc-search-bar-toggle` when it changes. |
clear() | Programmatically clears the value and fires rc-search-bar-clear + rc-search-bar-input. |
Events
| Event | Detail type | Description |
|---|---|---|
rc-search-bar-input | CustomEvent | Debounced after typing, immediate on clear; `detail: { value }` |
rc-search-bar-toggle | CustomEvent | When user interaction opens or closes the search view; `detail: { open }` |
rc-search-bar-suggestion-select | CustomEvent | When a datalist-derived suggestion is activated; `detail: { value, label }` |
rc-search-bar-clear | CustomEvent | When the clear button is activated |
Slots
| Name | Description |
|---|---|
(default) | The required native `<input type="search">` |
leading | Decorative leading icon; mark it `aria-hidden="true"` |
trailing | Optional trailing content after the clear button |
clear-icon | Optional glyph replacing the default clear glyph |
suggestions | Rich search view suggestions; takes precedence over datalist-derived suggestions. |
CSS Custom Properties
| Property | Default | Description |
|---|---|---|
--rc-search-bar-border | 1px solid ButtonBorder | Wrapper border; set to `none` in M3 theme (uses elevation instead) |
--rc-search-bar-shadow | none | Wrapper box-shadow for elevation; M3 theme sets Level 1 at rest |
--rc-search-bar-bg | Field | Wrapper background |
--rc-search-bar-color | FieldText | Wrapper text color |
--rc-search-bar-icon-color | GrayText | Leading icon color |
--rc-search-bar-clear-color | GrayText | Clear button glyph color |
--rc-search-bar-radius | var(--rc-control-radius,0.125em) | Wrapper border radius |
--rc-search-bar-height | var(--rc-control-block-size,2.5rem) | Wrapper block size |
--rc-search-bar-padding-inline | var(--rc-control-padding-inline,0.75rem) | Wrapper horizontal padding |
--rc-search-bar-gap | var(--rc-control-gap,0.25em) | Gap between icon, input, and clear button |
--rc-search-bar-input-font-size | Not specified | Input font size (inherits when unset) |
--rc-search-bar-input-font-family | Not specified | Input font family (inherits when unset) |
--rc-search-bar-input-color | Not specified | Input text color (inherits when unset) |
--rc-search-bar-view-bg | var(--rc-search-bar-bg) | Search view panel background |
--rc-search-bar-view-color | var(--rc-search-bar-color) | Search view panel text color |
--rc-search-bar-view-radius | var(--rc-search-bar-radius) | Search view panel radius |
--rc-search-bar-view-shadow | var(--rc-search-bar-shadow) | Search view panel shadow |
--rc-search-bar-view-border | var(--rc-search-bar-border) | Search view panel border |
--rc-search-bar-view-offset | 0.25rem | Gap between the search bar and the view panel below it |
--rc-search-bar-view-padding-block | 0.5rem | Search view suggestion list block padding |
--rc-search-bar-suggestion-min-block-size | 2.75rem | Datalist-derived suggestion row minimum block size |
--rc-search-bar-suggestion-padding-inline | 1rem | Datalist-derived suggestion inline padding |
--rc-search-bar-suggestion-hover-bg | ButtonFace | Datalist-derived suggestion hover/focus background |
CSS Parts
| Part | Description |
|---|---|
root | The wrapper element |
leading | Wrapper around the leading icon slot |
trailing | Wrapper around the trailing slot |
clear | The clear button |
view | Search view panel |
suggestions | Suggestions container |
suggestion | Datalist-derived suggestion button |