rc-search-bar
Search field wrapper for a native <input type="search"> with icon chrome, clear button, 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
- Main events
rc-search-bar-inputrc-search-bar-clear- 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.
API
Properties
| Property | Markup | Type | Default | Description |
|---|---|---|---|---|
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. |
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 |
|---|---|
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-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 |
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) |
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 |