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-toggle- Related
- Theme previews
Installation
- npm
- Yarn
npm install @rcarls/rc-search-bar
yarn add @rcarls/rc-search-bar
import '@rcarls/rc-search-bar/define';
Live demo
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>
API
Properties
| Property | Markup | Type | Default | Description |
|---|---|---|---|---|
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. |
clearLabel | clear-label | string | 'Clear search' | Accessible label for the clear button. |
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 `clear-label="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 |