# jb-searchbar

> searchbar web component

Latest version **3.5.0** (published 2026-09-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install jb-searchbar
pnpm add jb-searchbar
yarn add jb-searchbar
bun add jb-searchbar
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.5.0 |
| Published | 2026-09-11 |
| First published | 2020-09-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 4 |
| Unpacked size | 473 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 4 |
| Author | mohammad javad bathaei |
| Maintainers | javadbat |
| Keywords | jb, jb-searchbar, search, filter, search bar, web component |

## Links

- npm: https://www.npmjs.com/package/jb-searchbar
- Repository: https://github.com/javadbat/jb-searchbar
- Homepage: https://github.com/javadbat/jb-searchbar#readme
- Issues: https://github.com/javadbat/jb-searchbar/issues
- npm.io page: https://npm.io/package/jb-searchbar

## Dependencies (4)

- [jb-core](https://npm.io/package/jb-core.md) ^0.37.0
- [jb-icons](https://npm.io/package/jb-icons.md) ^2.5.0
- [jb-select](https://npm.io/package/jb-select.md) ^9.0.0
- [jb-validation](https://npm.io/package/jb-validation.md) ^1.0.0

## Alternatives

- [jsforce](https://npm.io/package/jsforce.md) — 851.2K weekly downloads
- [react-native-qrcode-svg](https://npm.io/package/react-native-qrcode-svg.md) — 693.5K weekly downloads
- [@salesforce/plugin-data](https://npm.io/package/@salesforce/plugin-data.md) — 394.9K weekly downloads
- [@backstage/plugin-search-common](https://npm.io/package/@backstage/plugin-search-common.md) — 308.5K weekly downloads
- [@chain-registry/types](https://npm.io/package/@chain-registry/types.md) — 38.4K weekly downloads

## Recent versions

- 3.5.0 (latest) — 2026-09-11
- 3.4.0 — 2026-09-01
- 3.3.0 — 2026-08-14
- 3.2.0 — 2026-08-13
- 3.1.1 — 2026-08-03
- 3.1.0 — 2026-07-19
- 3.0.2 — 2026-04-07
- 3.0.1 — 2026-04-06
- 3.0.0 — 2026-03-31
- 2.6.0 — 2025-10-11
- 2.5.0 — 2025-04-24
- 2.4.0 — 2025-01-18
- 2.3.1 — 2024-02-07
- 2.3.0 — 2024-02-07
- 2.2.0 — 2024-02-06
- … 17 more at https://npm.io/package/jb-searchbar/versions

## README

# jb-searchbar

[![Published on webcomponents.org](https://img.shields.io/badge/webcomponents.org-published-blue.svg)](https://www.webcomponents.org/element/jb-searchbar)
[![GitHub license](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://raw.githubusercontent.com/javadbat/jb-searchbar/main/LICENSE)
[![NPM Version](https://img.shields.io/npm/v/jb-searchbar)](https://www.npmjs.com/package/jb-searchbar)
![GitHub Created At](https://img.shields.io/github/created-at/javadbat/jb-searchbar)

`jb-searchbar` is a compact search and filter web component. It lets you render always-visible filters, optional user-selected filters, and a search button in one responsive bar.

- Supports any form-associated element as a filter.
- Supports always-visible filters through `slot="filter"`.
- Supports optional filters through `<jb-extra-filter slot="extra">`.
- Lets users add the same extra filter more than once unless `data-max-count` limits it.
- Collects normal and extra filter values through `.value`.
- Dispatches `search` when the search button is clicked or when `searchOnChange` is enabled.
- DOM-driven setup: define filters directly in markup instead of passing a large JavaScript configuration object.

## When to use

Use `jb-searchbar` when a page needs a compact query/filter surface for lists, tables, reports, or dashboards. See the [normal filter demo](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--normal) for the complete interaction.

Use a normal form when filters need a full-page layout, complex grouping, or submit/reset controls outside the searchbar.

## Demo

- Try the [interactive searchbar examples](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--normal), including [small sizing and loading](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--size), [search-on-change](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--search-on-change), and [dynamic extra filters](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--change-extra-fields).
- See the [CodePen example](https://codepen.io/javadbat/pen/rNjrZpy) for a standalone web-component setup.

## Using With JS Frameworks

<a href="https://github.com/javadbat/jb-searchbar/tree/main/react" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/React.js-jb--searchbar%2Freact-000.svg?logo=react&logoColor=%2361DAFB" height="30" /></a>

Other integrations: <a href="https://javadbat.github.io/design-system/?path=/docs/getting-started-framework-integration--docs#angular" target="_blank" rel="noopener noreferrer">Angular</a> · <a href="https://javadbat.github.io/design-system/?path=/docs/getting-started-framework-integration--docs#vue" target="_blank" rel="noopener noreferrer">Vue</a> · <a href="https://javadbat.github.io/design-system/?path=/docs/getting-started-framework-integration--docs#nuxt" target="_blank" rel="noopener noreferrer">Nuxt</a> · <a href="https://javadbat.github.io/design-system/?path=/docs/getting-started-framework-integration--docs#svelte" target="_blank" rel="noopener noreferrer">Svelte</a> · <a href="https://javadbat.github.io/design-system/?path=/docs/getting-started-framework-integration--docs#sveltekit" target="_blank" rel="noopener noreferrer">SvelteKit</a> · <a href="https://javadbat.github.io/design-system/?path=/docs/getting-started-framework-integration--docs#solidjs" target="_blank" rel="noopener noreferrer">SolidJS</a> · <a href="https://javadbat.github.io/design-system/?path=/docs/getting-started-framework-integration--docs#lit" target="_blank" rel="noopener noreferrer">Lit</a> · <a href="https://javadbat.github.io/design-system/?path=/docs/getting-started-framework-integration--docs#nextjs" target="_blank" rel="noopener noreferrer">Next.js</a> · <a href="https://javadbat.github.io/design-system/?path=/docs/getting-started-framework-integration--docs#astro" target="_blank" rel="noopener noreferrer">Astro</a> · <a href="https://javadbat.github.io/design-system/?path=/docs/getting-started-framework-integration--docs#blazor" target="_blank" rel="noopener noreferrer">Blazor</a> · <a href="https://javadbat.github.io/design-system/?path=/docs/getting-started-framework-integration--docs#server-rendered-templates" target="_blank" rel="noopener noreferrer">Server-rendered templates</a> · <a href="https://javadbat.github.io/design-system/?path=/docs/getting-started-framework-integration--docs#wordpress" target="_blank" rel="noopener noreferrer">WordPress</a> · <a href="https://javadbat.github.io/design-system/?path=/docs/getting-started-framework-integration--docs#alpinejs-and-htmx" target="_blank" rel="noopener noreferrer">Alpine.js and HTMX</a>

## Installation

```sh
npm i jb-searchbar
```

```js
import 'jb-searchbar';
```

```html
<jb-searchbar></jb-searchbar>
```

## How it works

`jb-searchbar` supports two filter types. The [normal filter demo](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--normal) shows both in one searchbar:

- Normal filters: always visible elements placed in `slot="filter"`.
- Extra filters: hidden filter templates placed inside `<jb-extra-filter slot="extra">`. The user selects one, fills its value, and submits it into the searchbar as a removable filter chip.

## API reference

### jb-searchbar attributes

| name | type | default | description |
| --- | --- | --- | --- |
| `search-on-change` | `boolean` | `false` | Runs `search()` after selected extra filters change. Empty attribute and `"true"` mean true; see [search-on-change](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--search-on-change). |
| `is-loading` | `boolean` | `false` | Plays the search icon loading animation. Empty attribute and `"true"` mean true. |
| `size` | `'sm' \| 'md'` | `md` style defaults | Visual size variant; see the [size and loading demo](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--size). |

### jb-searchbar properties

| name | type | readonly | description |
| --- | --- | --- | --- |
| `value` | `JBSearchbarValue` | yes | Current normal filter values plus selected extra filters; see the [value example](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--search-interaction). |
| `filterList` | `FilterItem[]` | no | Selected extra-filter chips. This is runtime state, not the available filter template list; see [filter management](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--filter-management). |
| `searchOnChange` | `boolean` | no | Runs `search()` after selected extra filters change; see [search-on-change](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--search-on-change). |
| `isLoading` | `boolean` | no | Plays or stops the search icon loading animation; see the [loading demo](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--size). |

### jb-searchbar methods

| name | returns | description |
| --- | --- | --- |
| `search()` | `void` | Dispatches the `search` event; see the [search interaction](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--search-interaction). |
| `deleteFilter(filterIndex)` | `void` | Removes a selected extra filter by index and dispatches `change`; see [filter management](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--filter-management). |
| `createFilterList()` | `FilterItem[]` | Creates the proxied selected-filter list used internally; see [filter management](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--filter-management). |
| `renderFilterList()` | `void` | Rerenders all selected filter chips from the current `filterList`. |

### jb-searchbar events

| event | description |
| --- | --- |
| `load` | Dispatched from `connectedCallback` before initialization; see the [events demo](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--events). |
| `init` | Dispatched from `connectedCallback` after initialization; see the [events demo](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--events). |
| `search` | Dispatched when the search button is clicked or `search()` is called; see the [search interaction](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--search-interaction). |
| `change` | Dispatched when a selected extra filter is added or removed; see [filter management](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--filter-management). |

### jb-searchbar slots

| slot | description |
| --- | --- |
| `filter` | Always-visible filter elements; see [normal filters](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--normal). |
| `extra` | One or more `<jb-extra-filter>` elements; see [extra filters](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--normal). |
| `divider` | Optional divider content between normal filters and extra filters; see the [size demo](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--size). |

## Normal filters

Use `slot="filter"` for always-visible inputs; see the [normal filter demo](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--normal).

Put always-visible filter elements inside an element with `slot="filter"`. The searchbar gathers elements that have a `name` and a `value` property.

```html
<jb-searchbar>
  <div slot="filter">
    <jb-input name="firstName" placeholder="First name"></jb-input>
    <jb-input name="lastName" placeholder="Last name"></jb-input>
    <jb-number-input name="age" placeholder="Age"></jb-number-input>
  </div>
</jb-searchbar>
```

## Extra filters

Use `<jb-extra-filter slot="extra">` for optional filters that become removable chips; see the [extra filter demo](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--normal).

Extra filters are filter templates that the user can choose from a dropdown. Place them inside `<jb-extra-filter slot="extra">`.

```html
<jb-searchbar>
  <jb-extra-filter slot="extra" placeholder="Choose filter">
    <jb-input name="firstName" data-label="First name"></jb-input>
    <jb-input name="lastName" data-label="Last name"></jb-input>
    <jb-number-input name="age" data-label="Age"></jb-number-input>
  </jb-extra-filter>
</jb-searchbar>
```

Use `label` or `data-label` on each filter template. Use `data-label` when the visible input label should not be used as the selected filter label.

> By Pressing `Esc` key intent field (selected field) will disappear and filter go to select column step again.

### data-max-count

Use `data-max-count` on a filter template to limit how many times it can be selected. The [normal filter demo](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--normal) includes a one-time filter.

```html
<jb-extra-filter slot="extra">
  <jb-number-input name="age" data-label="Age" data-max-count="1"></jb-number-input>
</jb-extra-filter>
```

## Updating `filterList`

`filterList` contains the extra filters that are currently selected and displayed as chips. Update the existing array with `push()` and remove items with `deleteFilter()` so `jb-searchbar` can keep the rendered chips in sync. Do not replace `filterList` with a new array.

```js
const searchbar = document.querySelector('jb-searchbar');

// Add a selected filter chip.
searchbar.filterList.push({
  name: 'status',
  label: 'Status',
  value: 'active',
  displayValue: 'Active',
});
// rerender filter list base on your update
searchbar.renderFilterList();
// Remove the selected filter at index 0.
searchbar.deleteFilter(0);
```

Each item requires `name`, `label`, `value`, and `displayValue`. Calling `filterList.push()` immediately renders the new chip, but changing a property of an existing item does not rerender that chip. Call `renderFilterList()` after editing existing items:

```js
searchbar.filterList[0].value = 'inactive';
searchbar.filterList[0].displayValue = 'Inactive';
searchbar.renderFilterList();
```

To replace an existing item, you can also remove it with `deleteFilter(index)` and then add the new item with `filterList.push(...)`. Direct calls to `filterList.push()` and `renderFilterList()` update the chip UI but do not dispatch `change`; call `searchbar.search()` afterward if the programmatic update should immediately trigger a search.

This property manages selected filter chips. To add or remove the available filter templates instead, update the children of `<jb-extra-filter>` and call `updateSlotElements()`.

## jb-extra-filter API

### jb-extra-filter attributes

| name | type | default | description |
| --- | --- | --- | --- |
| `placeholder` | `string` | localized default | Placeholder for the filter select; see the [extra filter demo](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--normal). |
| `size` | `'sm' \| 'md'` | `md` style defaults | Visual size forwarded to the internal select; see the [size demo](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--size). |
| `autofocus` | `boolean` | `false` | Focuses the internal select after it initializes when set as an empty attribute. |

### jb-extra-filter properties

| name | type | readonly | description |
| --- | --- | --- | --- |
| `inputState` | `'SELECT_COLUMN' \| 'FILL_VALUE'` | no | Current UI state; see the [extra filter interaction](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--normal). |
| `intentColumn` | `IntentColumn` | no | Current selected filter draft before it is submitted. |
| `extractDisplayValue` | `ExtractDisplayValueCallback` | no | Converts a filter value to the display string shown in the selected filter chip; see [display formatting](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--normal). |

### jb-extra-filter methods

| name | returns | description |
| --- | --- | --- |
| `updateSlotElements()` | `void` | Re-reads slotted filter templates and updates the select options; see the [dynamic filters demo](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--change-extra-fields). |
| `setFilterListSelectOptionList()` | `void` | Updates the available option list after selected filters change; see [filter management](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--filter-management). |

### jb-extra-filter events

| event | detail | description |
| --- | --- | --- |
| `load` | none | Dispatched from `connectedCallback` before parent lookup; see the [events demo](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--events). |
| `init` | none | Dispatched from `connectedCallback` after parent lookup; see the [events demo](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--events). |
| `intent-submit` | `{ name, label, displayValue, value }` | Dispatched when the user submits an extra filter value; see the [events demo](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--events). |

## Value

Read `.value` in a `search` or `change` handler; the [search interaction](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--search-interaction) shows the collected shape.

Read `.value` from the searchbar to get normal filters and selected extra filters.

```js
const searchbar = document.querySelector('jb-searchbar');

searchbar.addEventListener('search', () => {
  console.log(searchbar.value);
});
```

Each item contains:

| field | description |
| --- | --- |
| `name` | Filter element name. |
| `label` | Filter label from `label`, `data-label`, or fallback extraction. |
| `value` | Raw filter value. |
| `displayValue` | Display string for selected extra-filter chips. |

## Search on change

Set `searchOnChange` when selecting or removing an extra filter should trigger `search()` automatically. See the [search-on-change demo](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--search-on-change).

```html
<jb-searchbar search-on-change></jb-searchbar>
```

```js
const searchbar = document.querySelector('jb-searchbar');

searchbar.searchOnChange = true;
```

## Size and RTL

Use `size="sm"` for compact layouts, and verify the searchbar in right-to-left layouts with the [size/loading demo](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--size) and [RTL demo](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--rtl-sample).

## Loading state

Set `isLoading` in JavaScript or `is-loading` in HTML while a search request is running; see the [size and loading demo](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--size).

```js
const searchbar = document.querySelector('jb-searchbar');

searchbar.isLoading = true;
searchbar.isLoading = false;
```

## Display value formatting

Use `extractDisplayValue` to control the text shown in selected filter chips; the [normal filter demo](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--normal) includes a custom date formatter.

Use `extractDisplayValue` on `<jb-extra-filter>` when the raw value should be displayed differently.

```js
const extraFilter = document.querySelector('jb-extra-filter');

extraFilter.extractDisplayValue = ({ name, value, dom }) => {
  if (name === 'createdAt') {
    return dom.displayValue;
  }
  return String(value);
};
```

## Dynamic filter templates

When filter templates are added or removed at runtime, call `updateSlotElements()` on `jb-extra-filter`; the [dynamic filter demo](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--change-extra-fields) shows the available options updating.

## CSS parts and variables

### jb-searchbar parts

See the [normal searchbar demo](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--normal) for these parts in context.

| part | description |
| --- | --- |
| `dynamic-wrapper` | Wrapper around normal filters, selected extra filters, divider, and extra filter slot. |
| `filter-list` | Selected extra-filter chip list. |
| `search-button` | Search button wrapper. |

### jb-extra-filter parts

See the [extra filter interaction](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--normal) for the selector, intent input, and submit button parts.

| part | description |
| --- | --- |
| `column-select-wrapper` | Wrapper around the filter selector. |
| `intent-wrapper` | Wrapper shown while the user fills a selected filter value. |
| `intent-input-wrapper` | Wrapper where the selected filter input is moved. |
| `intent-submit-button` | Button that submits the selected extra filter value. |

| CSS variable name | description |
| --- | --- |
| `--jb-searchbar-divider-bg-color` | Divider background color. |
| `--jb-searchbar-filter-item-bg-color` | Selected extra-filter chip background color. |
| `--jb-searchbar-filter-item-border-radius` | Selected extra-filter chip border radius. |
| `--jb-searchbar-filter-item-color` | Selected extra-filter chip text color. |
| `--jb-searchbar-min-height` | Base searchbar minimum height. |
| `--jb-searchbar-min-height-sm` | Searchbar minimum height for `size="sm"`. |
| `--jb-searchbar-search-button-size` | Base search button size. |
| `--jb-searchbar-search-button-size-sm` | Search button size for `size="sm"`. |
| `--jb-extra-filter-submit-height` | Extra filter submit button height. |
| `--jb-extra-filter-submit-height-sm` | Extra filter submit button height for `size="sm"`. |
| `--jb-extra-filter-submit-width` | Extra filter submit button width. |
| `--jb-extra-filter-submit-width-sm` | Extra filter submit button width for `size="sm"`. |

```css
jb-searchbar {
  --jb-searchbar-filter-item-bg-color: #2563eb;
  --jb-searchbar-filter-item-color: #fff;
}
```

## Accessibility notes

- The search button is a clickable wrapper with an SVG icon. Add surrounding text or an external button if your page needs a visible text action; see the [search interaction](https://javadbat.github.io/design-system/?path=/story/components-jbsearchbar--search-interaction).
- Filter elements keep their own accessibility behavior while slotted or moved into the extra-filter intent area.
- Extra filter templates must have `name` attributes so values can be collected.

## Related Docs

- See [`jb-searchbar/react`](https://github.com/javadbat/jb-searchbar/tree/main/react) if you want to use this component in React.
- See [`jb-select`](https://github.com/javadbat/jb-select) for the internal select used by `jb-extra-filter`.
- See [All JB Design System Component List](https://javadbat.github.io/design-system/) for more components.
- Use [Contribution Guide](https://github.com/javadbat/design-system/blob/main/docs/contribution-guide.md) if you want to contribute to this component.

## AI agent notes

- Import `jb-searchbar` once before using `<jb-searchbar>` or `<jb-extra-filter>`.
- Put always-visible filters inside an element with `slot="filter"`.
- Put `<jb-extra-filter slot="extra">` inside `<jb-searchbar>` for optional filters.
- Put optional filter templates as children of `<jb-extra-filter>`.
- Use `data-label` on filter templates when the selected chip label should differ from the input label.
- Use `data-max-count="1"` when a filter can only be selected once.
- Read `searchbar.value` inside `search` or `change` events.
- Use `searchOnChange` as a JavaScript property or `search-on-change` as an HTML attribute.
- Use `isLoading` as a JavaScript property or `is-loading` as an HTML attribute.
- This package includes [`custom-elements.json`](./custom-elements.json) and points to it with the package.json `customElements` field. The field is documented by the Custom Elements Manifest project in [Referencing manifests from npm packages](https://github.com/webcomponents/custom-elements-manifest#referencing-manifests-from-npm-packages).
- In `custom-elements.json`, `exports.kind: "custom-element-definition"` maps `jb-searchbar` and `jb-extra-filter` tag names to their implementation classes.

---
_Source: https://npm.io/package/jb-searchbar · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._