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 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, including small sizing and loading, search-on-change, and dynamic extra filters.
• See the CodePen example for a standalone web-component setup.

Using With JS Frameworks

Other integrations: Angular · Vue · Nuxt · Svelte · SvelteKit · SolidJS · Lit · Next.js · Astro · Blazor · Server-rendered templates · WordPress · Alpine.js and HTMX

Installation

npm i jb-searchbar

import 'jb-searchbar';

<jb-searchbar></jb-searchbar>

How it works

jb-searchbar supports two filter types. The normal filter demo 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. | | size | 'sm' \| 'md' | md style defaults | Visual size variant; see the size and loading demo. |

jb-searchbar properties

| name | type | readonly | description | | --- | --- | --- | --- | | value | JBSearchbarValue | yes | Current normal filter values plus selected extra filters; see the value example. | | filterList | FilterItem[] | no | Selected extra-filter chips. This is runtime state, not the available filter template list; see filter management. | | searchOnChange | boolean | no | Runs search() after selected extra filters change; see search-on-change. | | isLoading | boolean | no | Plays or stops the search icon loading animation; see the loading demo. |

jb-searchbar methods

| name | returns | description | | --- | --- | --- | | search() | void | Dispatches the search event; see the search interaction. | | deleteFilter(filterIndex) | void | Removes a selected extra filter by index and dispatches change; see filter management. | | createFilterList() | FilterItem[] | Creates the proxied selected-filter list used internally; see 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. | | init | Dispatched from connectedCallback after initialization; see the events demo. | | search | Dispatched when the search button is clicked or search() is called; see the search interaction. | | change | Dispatched when a selected extra filter is added or removed; see filter management. |

jb-searchbar slots

| slot | description | | --- | --- | | filter | Always-visible filter elements; see normal filters. | | extra | One or more <jb-extra-filter> elements; see extra filters. | | divider | Optional divider content between normal filters and extra filters; see the size demo. |

Normal filters

Use slot="filter" for always-visible inputs; see the normal filter demo.

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

<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.

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

<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 includes a one-time filter.

<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.

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:

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. | | size | 'sm' \| 'md' | md style defaults | Visual size forwarded to the internal select; see the size demo. | | 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. | | 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. |

jb-extra-filter methods

| name | returns | description | | --- | --- | --- | | updateSlotElements() | void | Re-reads slotted filter templates and updates the select options; see the dynamic filters demo. | | setFilterListSelectOptionList() | void | Updates the available option list after selected filters change; see filter management. |

jb-extra-filter events

| event | detail | description | | --- | --- | --- | | load | none | Dispatched from connectedCallback before parent lookup; see the events demo. | | init | none | Dispatched from connectedCallback after parent lookup; see the events demo. | | intent-submit | { name, label, displayValue, value } | Dispatched when the user submits an extra filter value; see the events demo. |

Value

Read .value in a search or change handler; the search interaction shows the collected shape.

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

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.

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

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 and RTL demo.

Loading state

Set isLoading while a search request is running; see the size and loading demo.

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 includes a custom date formatter.

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

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

extraFilter.extractDisplayValue = ({ name, value, dom }) => {
  if (name === 'createdAt') {
    return dom.inputValue;
  }
  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 shows the available options updating.

CSS parts and variables

jb-searchbar parts

See the normal searchbar demo 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 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". |

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.
• 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 if you want to use this component in React.
• See jb-select for the internal select used by jb-extra-filter.
• See All JB Design System Component List for more components.
• Use Contribution Guide 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.
• This package includes 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.
• In custom-elements.json, exports.kind: "custom-element-definition" maps jb-searchbar and jb-extra-filter tag names to their implementation classes.