Search
Query entry for tables, pages, and global document search.
Installation
Import the component in your screen:
import { Search } from '@commenda/pathfinder/search';Load the stylesheet once in your app root, after host styles:
import '@commenda/pathfinder/styles.css';Pathfinder ships precompiled CSS; no Tailwind setup is required. In Next.js App Router, put interactive state and callbacks in a client component. See installation for the workspace setup.
API reference
| Prop | Type | Behavior |
|---|---|---|
variant | "fixed"|"expandable"|"global" | fixed; heights 28/28/40px |
loadingConfig | ObjectView fields | Spinner replaces search icon |
shortcutConfig | ObjectView fields | Opt-in scoped shortcut; ignores typing targets |
onSearch | (query: string) => void | Enter submission; ignored during IME composition |
labelConditional | string | Visible field label. Supply an accessible name when it is omitted. |
hideLabel | boolean | Visually hide the label while preserving its accessible name. |
aria-labelConditional | string | Accessible name when the field has no visible label. |
requiredConditional | boolean | Mark the field as required. See validation guidance for the component. |
labelConfig | ObjectView fields · 2 shapes | Choose either optionalLabel or help, never both. never excludes the other field. |
description | string | Supporting guidance associated with the field. |
errorConfig | ObjectView fields | Validation message and when it becomes visible. |
disableConfig | DisableConfigView fields | Disabled state with an optional explanation. |
valueConditional | string | — |
onValueChangeConditional | (value: string) => void | — |
defaultValue | string | — |
loadingConfigObject fields
| Field | Type | Requirement |
|---|---|---|
isLoading | boolean | Required |
label | string | Optional |
shortcutConfigObject fields
| Field | Type | Requirement |
|---|---|---|
key | string | Required |
label | string | Required |
scopeId | string | Required |
labelConfigObject fields
Choose one of these 2 shapes. Do not combine fields excluded by the selected shape.
Option 1
| Field | Type | Requirement |
|---|---|---|
optionalLabel | string | Required |
Do not supply: help.
Option 2
| Field | Type | Requirement |
|---|---|---|
help | string | Required |
Do not supply: optionalLabel.
errorConfigObject fields
| Field | Type | Requirement |
|---|---|---|
message | string | Required |
reveal | "after-blur" | "immediate" | Optional |
disableConfigObject fields
| Field | Type | Requirement |
|---|---|---|
isDisabled | boolean | Required |
reason | string | Optional |
Supports Input’s shared field presentation and native search-input attributes. Use hideLabel where the surrounding toolbar supplies visual context; an accessible label is still required.
Keyboard and request behavior
Application code handles debounce and requests; onValueChange is immediate. onSearch is Enter submission, not each keystroke. Escape clears the query, then blurs a fixed/global input or collapses expandable search and restores trigger focus. The clear button clears and folds expandable search. Loading is application-owned.
A result overlay handles Escape first through onKeyDown and preventDefault; the field then retains its query. Search result navigation is a documented composition, separate from selecting a saved value. Do not implement a second global shortcut listener on every instance: shortcutConfig binds only to the specified scope element and ignores editing targets.
Variants
States
Results
Read selection and search rules for source provenance, API ownership, and constraints.
Design rules
Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.
Source rules
| Rule | Figma source | Contract |
|---|---|---|
| SEARCH-001 | 636:31822 | Fixed/expandable 28px; expandable opens to 220px; global 40px/max720. |
| SEARCH-002 | 637:32230, 637:32236 | Expandable in table toolbar; result counts belong in table range text. |
| SEARCH-003 | 637:32193, 637:1779 | Escape closes results, clears, then blurs/collapses. Clear folds expandable search. |
Sources: Search, Select, MultiSelect. The supplied Select node 182:1182 is its dimensions frame; 180:1177 is the actual component set.
Accessibility and forms
Labels, descriptions, error reveal, and disable reasons follow the shared field contract. Single selection serializes one ID; multiple selection serializes repeated names. Trigger refs and form reset work for both primitive paths. Searchable popups provide an explicitly named query input. Load more and retry are keyboard-accessible buttons outside the option list.
Tag remove buttons are siblings of the trigger, never nested inside it. Long selected labels remain available through tooltips. Search result compositions must handle overlay Escape before field clear/collapse through preventDefault.
Flags, chevrons, and clear/remove icons sit in explicit square flex containers with both axes centered. Do not rely on inline SVG baseline alignment or compensate with pixel offsets. The selected value, tags, and trailing controls share the field’s vertical center. Row Checkbox instances are inert visual indicators; the option owns selection and accessibility semantics.