Pricing

SearchBox handbook

v1.2.0 · @snowui-design-system/components

License: Before reading component documentation, source, or npm usage instructions for the first time, read the full LICENSE. Reuse that review for the same task and version. Public API configuration and internal implementation changes have different license implications. All components use the unified runtime package; source rights remain governed by the license.

Overview

A fully clickable control that opens a search popup. It can include a keyboard shortcut hint and suits global search.

When to use it

Use it as a clickable entry to open a global search popup, not as an input for editing a query. Use SearchInput when users should type directly in a toolbar or list.

  • This is a clickable search entry. bind:open synchronizes popup state; value displays the current query.

  • Compose a popup or shortcut hint with children. Use SearchInput when the query must be editable directly.

  • The default placeholder and clear action follow LocaleProvider. Explicit placeholder values, including an empty string, and aria-label take priority; the query remains unchanged.

Quick start

This example shows the recommended basic composition. See the sections below for more cases and composition limits.

<script lang="ts">	import { SearchBox } from '@snowui-design-system/components';	import { Kbd, Popover, SearchInput, MenuItem, Icon, Avatar } from '@snowui-design-system/components';	import { MagnifyingGlass, AvatarByewind } from '@snowui-design-system/resource-svelte';</script> <Popover template id="search-box-usage-popup" size="md" closeOnSelect={false} style="width: 20rem;">    <SearchInput placeholder="Search" />    <MenuItem value="overview" closeOnSelect={true}>        <Icon as="leading"><MagnifyingGlass /></Icon>        Search history: Overview    </MenuItem>    <MenuItem value="contact-byewind" closeOnSelect={true}>        <Avatar src={AvatarByewind} size={24} as="leading" />        Contact: Byewind    </MenuItem></Popover> <SearchBox data-popover-target="search-box-usage-popup" style="width: 10rem;" placeholder="Search">    <Kbd as="trailing" variant="solid" style="background-color: var(--surface-3);">⌘K</Kbd></SearchBox>

API

Keyword Type Default Description
parts ComponentPartsOf<{ Button: typeof Button }> — Configures the internally generated clear Button. Explicit child content does not consume this default.
variant "gray" | "outline" "gray" Search control style
gap number — Inherited Frame gap token index. Omit it to retain the preferred component gap; explicit values override that preference. Effective graphics/text spacing remains at least 4 CSS px, including zero, root-font scaling and gap scaling.
value string | number — Current query text or displayed value
placeholder string — Placeholder text. When omitted, searchBox.placeholder provides the localized placeholder (“Search” in en-US). An explicit empty string is preserved.
open boolean false Popup open state; supports bind:open
disabled boolean false Disables the trigger
readonly boolean false Read-only trigger; does not open the popup
showSearchIcon boolean true Whether to render the default search icon
collapseBelow number — When the component’s own width is at or below this px threshold, retains only the leading search icon. Disabled when omitted.
clearable boolean true Whether to show the clear button when a value is present
children Snippet — External leading or trailing content, such as Kbd
onOpenChange (open: boolean) => void — Callback when open state changes
onClear () => void — Clear callback
onclick (event: MouseEvent) => void — Called after entry click with the original MouseEvent. When enabled and not read-only, the component opens the search popup first; the callback cannot undo that opening.
onkeydown (event: KeyboardEvent) => void — Called after handling Escape to close or Enter/Space to open, with the original KeyboardEvent. It cannot undo the state change already made.

See the base component documentation for inherited capabilities not redeclared here. This table lists only named public Props declared by this component.

Usage boundaries and details

Feature overview

  • Two styles: gray and outline

  • The default leading icon is Search

  • The consumer supplies an external Kbd through trailing children; it is not included by default.

  • With a value, a clear X appears using visual rules from Input.

  • Click anywhere on the trigger to open the popup.

  • collapseBelow retains only the leading search icon when the component itself becomes narrow. Minimum width is its actual left/right padding plus the intrinsic width of the leading Icon.

  • No outer focus ring is shown. Visual state is consistent after mouse clicks and keyboard operations such as Escape.

Usage examples

<SearchBox placeholder="Search">  <Kbd as="trailing" variant="solid" style="background-color: var(--surface-3);">/</Kbd></SearchBox>
 <SearchBox collapseBelow={80} placeholder="Search" />
<script lang="ts">  import { Kbd } from '@snowui-design-system/components';  import { SearchBox } from '@snowui-design-system/components';  let open = $state(false);</script> <SearchBox variant="outline" bind:open>  <Kbd as="trailing" variant="solid" style="background-color: var(--surface-3);">⌘K</Kbd></SearchBox>

This section is protected. An AI must request user review before modifying it.

SearchBox style overrides

Read the full LICENSE first; reuse that review for the same task, version, and scope.

First use public component Props to match the desired appearance, preserving the existing look where possible. If changes are necessary, follow the style selection and override order: use your own class (including Tailwind already in the project) or an instance style. The names below are public overrides actually consumed by source; check their scope and do not modify private DOM. Choose the correct SnowUI token family. External apps need not install SnowUI website utilities.

Variable Purpose and default reference
--snowui-search-box-background-blur-override Background blur (default 1.25rem = 20px)
--snowui-search-box-background-override Background (see component source for the default)
--snowui-search-box-font-size-override Font size (default var(--text-14) = 14px)
--snowui-search-box-gap-override Gap (default var(--gap-2) = 8px)
--snowui-search-box-icon-color-override Icon color (see component source for the default)
--snowui-search-box-icon-hover-color-override Icon hover color (see component source for the default)
--snowui-search-box-line-height-override Line height (default var(--leading-14) = 20px)
--snowui-search-box-padding-override Vertical/horizontal padding (default 4px/8px)
--snowui-search-box-placeholder-color-override Placeholder color (see component source for the default)
--snowui-search-box-radius-override Corner radius (default var(--radius-4) = 16px)
--snowui-search-box-width-override Width (see component source for the default)

Design guide · Tokens · Composition boundaries

SearchBox types and states

Required Props: no named required Props.

Two-way binding: bind:value, bind:open, bind:element.

Inherited declaration: Omit<FrameProps, "children" | "tag">. Consult the base component’s public documentation for inherited capabilities; fields excluded by Omit cannot be used as if inherited unchanged.

Shared Frame API · Back to API

The following type declarations are actually referenced by public Props and come from source. A Svelte Snippet denotes a content fragment; ComponentProps denotes the Props of the corresponding component.

ComponentPartsOf

Source: components/src/logic/component-parts.svelte.ts

export type ComponentPartsOf<    T extends Record<string, Component<any>>,> = {    [K in keyof T]?: ConfigurableComponentPartProps<T[K]>;};

ConfigurableComponentPartProps

Source: components/src/logic/component-parts.svelte.ts

export type ConfigurableComponentPartProps<C extends Component<any>> = Partial<    Omit<ComponentProps<C>, ComponentPartControlledKey>>;

ComponentPartControlledKey

Source: components/src/logic/component-parts.svelte.ts

export type ComponentPartControlledKey =    | "children"    | "as"    | "value"    | "defaultValue"    | "open"    | "selected"    | "checked"    | "disabled"    | "readonly"    | "id"    | `on${string}`    | `aria-${string}`;