@htmlbricks/hb-searchbar

hb-searchbar (searchbar)

Category: utilities
Tags: utilities, search
Package: @htmlbricks/hb-searchbar

Overview

hb-searchbar is a Bulma-styled search control that lives in a shadow root. It renders either a single-line <input type="search"> or a multiline <textarea>, an in-field submit (magnifier) button, and an optional suggestion dropdown driven by a searchlist you pass in.

Use it when you want a self-contained query field with debounced “search while typing”, optional fixed or fuzzy-matched suggestions, rich rows (icons, badges, tags, links), and explicit search / clear custom events for your host application.

Custom element

<hb-searchbar …></hb-searchbar>

Attributes and properties

Web component attributes are strings. For structured data (searchlist, input_info), pass JSON as a string attribute (or set the corresponding property with a parsed object in JavaScript). Boolean-like flags use yes / no where noted.

Name	Required	Description
value	Yes	Current query text.
id	No	Host id string; included on clear event detail.
style	No	Inline style string for the host (optional).
searchlabel	No	Placeholder text. Default: "Search".
minlength	No	Minimum query length (number) before input-driven search runs and before the preview can open; default 0. Compares value.length to this number.
searchlist	No	Array of suggestions (TSearchListItem[]). From HTML, use a JSON string. Parsed at runtime if a string is received.
input_info	No	Single TSearchListItem shown when its text equals the current value (JSON string from HTML).
textarea	No	Multiline mode: "yes", "true", or "" (empty string) enables <textarea>; otherwise a search <input> is used.
disable_preview	No	When "yes", "true", or "on", the suggestion dropdown does not open. Any other value (including "no", "false", "off") allows preview when other conditions are met.
disabled	No	"yes" disables the field and action buttons; "no" or omitted leaves them enabled.

TSearchListItem shape

Each suggestion (and input_info) uses:

Field	Type	Notes
id	string	Required stable id for the row.
text	string	Primary label.
url	string	Optional link target for the row.
icon	string	Optional Bootstrap Icons icon name (without bi- prefix in markup; the component uses bi bi-{icon} classes).
number_of_results	number	Optional count display.
fixed	boolean	When true, the row stays visible regardless of the current filter.
tags	TSearchListItemTag[]	Optional chips: text, color, icon.
badge	TSearchListItemBadge	Optional badge: text, color, icon.

Tags and badges use Bulma-style color names (for example primary, success, danger) as consumed by the row renderer.

How the suggestion list behaves

• Filtering: Non-fixed items are shown when their text contains the current value (case-insensitive substring match). Items with fixed: true are always included.
• Opening: The dropdown is shown when preview is not disabled, the query length is greater than minlength, and the field is considered “open” after interaction (typing opens it; choosing an action may close it depending on the trigger).
• Debounced input search: After input changes, a 500 ms debounce runs; if the value is non-empty and satisfies minlength, a search event fires with by: "input". Enter in the field triggers submit-style search (by: "button") without waiting for the timer.
• Submit button: Clicks dispatch search with by: "button".
• Picking a suggestion: Dispatches search with by: "searchlist" and updates the field text to the chosen item’s text.
• Clearing: For the native search input, clearing via the browser’s search clear control dispatches clear with { id }. In textarea mode, an explicit clear button empties the value, dispatches clear, and closes the dropdown. Clicks outside the host close the dropdown without clearing the value.

Events

Listen with addEventListener on the host element.

Event	Detail (TypeScript Events)
search	{ input: string; by: "button" | "input" | "searchlist"; item?: TSearchListItem } — when the user picks a suggestion, item is the matched list entry; for by: "input" or "button", item is omitted.
clear	{ id: string } — the host id attribute (empty string if unset).

Styling

Bulma CSS variables

The component uses Bulma layout and form patterns inside the shadow tree. Theme it with --bulma-* variables on a wrapping scope or :root / body so they apply to :host. Relevant groups include:

• Accent and focus: --bulma-primary, --bulma-danger
• Surfaces and chrome: --bulma-background, --bulma-scheme-main, --bulma-border, --bulma-border-weak
• Typography: --bulma-text, --bulma-text-strong, --bulma-input-placeholder-color
• Shape and stacking: --bulma-radius, --bulma-radius-small, --bulma-dropdown-content-z

See Bulma CSS variables for the full variable system.

Component-specific variables (--hb-searchbar-*)

These override frosted layers and panel backgrounds (defaults use color-mix() with Bulma tokens):

• --hb-searchbar-host-background — host background at rest
• --hb-searchbar-host-background-focus — host background while focused
• --hb-searchbar-input-strip-background — input row strip
• --hb-searchbar-dropdown-panel-background — open suggestion panel
• --hb-searchbar-input-glass-blur — backdrop blur behind the focused field
• --hb-searchbar-input-glass-saturate — backdrop saturation factor

Authoritative descriptions and defaults are listed in extra/docs.ts (styleSetup.vars).

CSS shadow parts

Part	Targets
dropdown-menu	Open suggestion list panel
search-input	Native <input> or <textarea>
search-input-glass	Frosted layer behind the field while focused
search-submit	In-field magnifier / submit control

Example:

hb-searchbar::part(search-submit) {
  color: var(--bulma-primary);
}

Icons and assets

The component loads Bootstrap Icons from jsDelivr in the shadow document head (bootstrap-icons.css). Icon names in searchlist / input_info refer to that font set.

Slots

None (htmlSlots is empty).

Usage notes

• Autocomplete: The control sets autocomplete="off". Browsers may still offer their own UI; behavior varies.
• Storybook: Controls may expose names like initial_value for demos; the runtime contract for authors is types/webcomponent.type.d.ts (value is the live bound field).
• Structured props from HTML: Always serialize searchlist and input_info as JSON strings on attributes; never rely on passing raw objects through HTML attributes.

Examples

Minimal search field

<hb-searchbar
  value=""
  searchlabel="Search"
></hb-searchbar>

Suggestions with JSON searchlist

<hb-searchbar
  value=""
  searchlabel="Try a suggestion"
  searchlist='[{"id":"1","text":"Documentation"},{"id":"2","text":"API reference"}]'
></hb-searchbar>

Multiline textarea mode

<hb-searchbar
  value=""
  searchlabel="Describe your query"
  textarea="yes"
  searchlist='[{"id":"1","text":"Example prompt"}]'
></hb-searchbar>

Disable preview, require two characters before input search

<hb-searchbar
  value=""
  disable_preview="yes"
  minlength="2"
></hb-searchbar>

JavaScript: listen for search and clear

const el = document.querySelector("hb-searchbar");

el.addEventListener("search", (e) => {
  const { input, by } = e.detail;
  console.log("search", { input, by });
});

el.addEventListener("clear", (e) => {
  console.log("cleared", e.detail.id);
});

License

Package metadata references Apache-2.0 (see LICENSE.md in the published package when consuming from npm).