ui/components/search-input

Search Input

Terminal-styled search input with / prefix and keyboard event callbacks. Supports controlled and uncontrolled modes.

Preview

tsx

1 import { SearchInput } from "@/components/ui/search-input";2 3 export default function SearchInputDefault() {4   return <SearchInput placeholder="Search components..." />;5 }6

Installation

$pnpm exec dgadd add ui/search-input

[Installs to]src/components/ui/search-input[Item]ui/search-input

dgadd is not public on npm yet. Until the first release, pack @diffgazer/add from the repository and install that tarball into this app, which is what puts dgadd on pnpm exec.

UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS once packages are available.

Usage

tsx

1 import { SearchInput } from "@/components/ui/search-input";2 3 export default function SearchInputDefault() {4   return <SearchInput placeholder="Search components..." />;5 }6

Examples

Custom

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { SearchInput } from "@/components/ui/search-input";5 6 export default function SearchInputCustom() {7   const [query, setQuery] = useState("");8   const [submitted, setSubmitted] = useState("");9   return (10     <div className="flex flex-col gap-4">11       <SearchInput12         value={query}13         onChange={setQuery}14         placeholder="Type and press Enter..."15         onEnter={() => setSubmitted(query.trim())}16         // SearchInput clears a non-empty value itself; onEscape only fires once the17         // input is already empty, so this discards the last result.18         onEscape={() => setSubmitted("")}19         prefix={20           <span className="text-foreground font-bold" aria-hidden="true">21             $22           </span>23         }24       />25       <output className="font-mono text-xs text-muted-foreground">26         {submitted ? `Searched for "${submitted}"` : "Nothing searched yet"}27       </output>28       <SearchInput29         defaultValue=""30         placeholder="Uncontrolled search"31         prefix={32           <span className="text-foreground font-bold" aria-hidden="true">33             &gt;34           </span>35         }36       />37     </div>38   );39 }40

Sizes, invalid, disabled

Preview

tsx

1 import { SearchInput } from "@/components/ui/search-input";2 3 export default function SearchInputStates() {4   return (5     <div className="flex max-w-sm flex-col gap-4">6       <SearchInput size="sm" placeholder="Small" aria-label="Small search" />7       <SearchInput size="md" placeholder="Medium (default)" aria-label="Medium search" />8       <SearchInput size="lg" placeholder="Large" aria-label="Large search" />9       <SearchInput aria-invalid placeholder="Invalid" aria-label="Invalid search" />10       <SearchInput disabled placeholder="Disabled" aria-label="Disabled search" />11     </div>12   );13 }14

Keyboard Navigation

Preview

tsx

1 "use client";2 3 import { useId, useRef, useState } from "react";4 import { SearchInput } from "@/components/ui/search-input";5 // @hidden-imports-ok — demo imports the useNavigation re-export from the hidden use-navigation hook registry item6 import { useNavigation } from "@/hooks/use-navigation";7 8 const items = ["Components", "Hooks", "Utilities", "Themes", "Plugins"];9 10 export default function SearchInputKeyboard() {11   const listboxId = useId();12   const [query, setQuery] = useState("");13   const listRef = useRef<HTMLUListElement>(null);14 15   const getOptionId = (item: string) => `${listboxId}-${item.toLowerCase()}`;16 17   const filtered = items.filter((item) => item.toLowerCase().includes(query.toLowerCase()));18 19   const { isHighlighted, highlighted, onKeyDown, highlight } = useNavigation<string>({20     containerRef: listRef,21     role: "option",22     wrap: true,23     // Starts highlighted so the keyboard treatment is visible without pressing a key.24     defaultHighlighted: "Hooks",25     onEnter: (value) => setQuery(value),26   });27 28   return (29     <div className="w-72 border border-border">30       <SearchInput31         // The frame owns the outer hairline; the input keeps only the seam that32         // separates it from the results list.33         className="border-0 border-b"34         value={query}35         onChange={(v) => {36           setQuery(v);37           highlight(null);38         }}39         placeholder="Search items..."40         role="combobox"41         aria-controls={listboxId}42         aria-activedescendant={highlighted ? getOptionId(highlighted) : undefined}43         aria-expanded={filtered.length > 0}44         aria-autocomplete="list"45         onEscape={() => highlight(null)}46         onKeyDown={onKeyDown}47       />48       {/* biome-ignore lint/a11y/noNoninteractiveElementToInteractiveRole: WAI-ARIA combobox pattern — role="listbox" on a <ul> is the standard popup list paired with the combobox input. */}49       <ul ref={listRef} id={listboxId} role="listbox" className="font-mono text-xs">50         {filtered.map((item) => (51           // biome-ignore lint/a11y/useFocusableInteractive: options stay non-focusable; the combobox input keeps focus and aria-activedescendant tracks the active option.52           <li53             key={item}54             id={getOptionId(item)}55             // biome-ignore lint/a11y/noNoninteractiveElementToInteractiveRole: WAI-ARIA listbox pattern — role="option" on a <li> is the standard option element inside the listbox.56             role="option"57             data-value={item}58             aria-selected={isHighlighted(item)}59             className={`flex items-center px-3 py-1.5 pointer-coarse:min-h-11 ${60               isHighlighted(item)61                 ? "bg-foreground text-background font-bold"62                 : "text-muted-foreground"63             }`}64           >65             {item}66           </li>67         ))}68       </ul>69     </div>70   );71 }72

API Reference

SearchInput

Name	Type	Default	Description
value	string	—	Controlled search value.
defaultValue	string	""	Initial search value for uncontrolled usage.
onChange	(value: string) => void	—	Called with the next search value when the native input changes.
onEscape	() => void	—	Called when Escape is pressed and the event was not already handled.
onEnter	() => void	—	Called when Enter is pressed and the event was not already handled.
prefix	ReactNode	"/"	Prefix content before the input. Pass null to hide it.
clearLabel	string	"Clear search"	Accessible name for the clear button shown while the input has a value.
placeholder	string	"Search..."	Native placeholder. Also becomes the fallback aria-label unless aria-label is supplied.
size	"sm" \| "md" \| "lg"	"md"	Height/padding/font size token, shared with Input and InputGroup.
inputClassName	string	—	Classes merged onto the inner input. The public seam for styling the field itself (text overflow, alignment) instead of reaching through the shell with a `[&_input]` selector.
aria-label	string	placeholder	Accessible name forwarded to the native search input. Defaults to the placeholder text.
aria-invalid	boolean \| "true" \| "false" \| "grammar" \| "spelling"	—	Forwarded to the native search input and used by the wrapper for invalid styling.
disabled	boolean	false	Disables the native search input.

Accessibility

Keyboard Navigation

SearchInput provides onEscape and onEnter callback props. For arrow-key navigation in an adjacent list, use the onKeyDown prop or @diffgazer/keys's useNavigation hook. The search-input-keyboard example shows how to wire arrow keys via onKeyDown.

Key	Action
Escape	Clears the current value when it is non-empty; otherwise calls onEscape when provided.
Enter	Calls onEnter when provided.
ArrowRight	With the caret and selection at the end of a non-empty value, moves focus to the clear button; elsewhere it keeps its native caret move.
ArrowLeft (on the clear button)	Returns focus to the search input.
Arrow keys / other keys	Forward through onKeyDown so a parent listbox, combobox, or custom search flow can own navigation.

With keyboard navigation

Preview

tsx

1 "use client";2 3 import { useId, useRef, useState } from "react";4 import { SearchInput } from "@/components/ui/search-input";5 // @hidden-imports-ok — demo imports the useNavigation re-export from the hidden use-navigation hook registry item6 import { useNavigation } from "@/hooks/use-navigation";7 8 const items = ["Components", "Hooks", "Utilities", "Themes", "Plugins"];9 10 export default function SearchInputKeyboard() {11   const listboxId = useId();12   const [query, setQuery] = useState("");13   const listRef = useRef<HTMLUListElement>(null);14 15   const getOptionId = (item: string) => `${listboxId}-${item.toLowerCase()}`;16 17   const filtered = items.filter((item) => item.toLowerCase().includes(query.toLowerCase()));18 19   const { isHighlighted, highlighted, onKeyDown, highlight } = useNavigation<string>({20     containerRef: listRef,21     role: "option",22     wrap: true,23     // Starts highlighted so the keyboard treatment is visible without pressing a key.24     defaultHighlighted: "Hooks",25     onEnter: (value) => setQuery(value),26   });27 28   return (29     <div className="w-72 border border-border">30       <SearchInput31         // The frame owns the outer hairline; the input keeps only the seam that32         // separates it from the results list.33         className="border-0 border-b"34         value={query}35         onChange={(v) => {36           setQuery(v);37           highlight(null);38         }}39         placeholder="Search items..."40         role="combobox"41         aria-controls={listboxId}42         aria-activedescendant={highlighted ? getOptionId(highlighted) : undefined}43         aria-expanded={filtered.length > 0}44         aria-autocomplete="list"45         onEscape={() => highlight(null)}46         onKeyDown={onKeyDown}47       />48       {/* biome-ignore lint/a11y/noNoninteractiveElementToInteractiveRole: WAI-ARIA combobox pattern — role="listbox" on a <ul> is the standard popup list paired with the combobox input. */}49       <ul ref={listRef} id={listboxId} role="listbox" className="font-mono text-xs">50         {filtered.map((item) => (51           // biome-ignore lint/a11y/useFocusableInteractive: options stay non-focusable; the combobox input keeps focus and aria-activedescendant tracks the active option.52           <li53             key={item}54             id={getOptionId(item)}55             // biome-ignore lint/a11y/noNoninteractiveElementToInteractiveRole: WAI-ARIA listbox pattern — role="option" on a <li> is the standard option element inside the listbox.56             role="option"57             data-value={item}58             aria-selected={isHighlighted(item)}59             className={`flex items-center px-3 py-1.5 pointer-coarse:min-h-11 ${60               isHighlighted(item)61                 ? "bg-foreground text-background font-bold"62                 : "text-muted-foreground"63             }`}64           >65             {item}66           </li>67         ))}68       </ul>69     </div>70   );71 }72

Notes

Controlled & Uncontrolled

Pass value + onChange for controlled mode. Pass defaultValue (or nothing) for uncontrolled mode. Works like every other @diffgazer/ui component via useControllableState.

Keyboard Callbacks

SearchInput provides onEscape and onEnter callback props for common search patterns (clear and submit). For arrow-key list navigation, use onKeyDown or @diffgazer/keys's useNavigation hook.

Custom Prefix

The prefix prop replaces the default / character with any ReactNode. Set prefix={null} to hide it entirely.

Size Variants

Pass size="sm", size="md" (default), or size="lg" to control the input and wrapper sizing.

Invalid & Disabled

Set aria-invalid to show destructive border styling. Pass disabled to prevent interaction.

Source

Install via CLI: pnpm exec dgadd add ui/search-input.

Highlighted source loads after this disclosure opens. Browse the source repository.

Search Input

Installation

Usage

Examples

Custom

Sizes, invalid, disabled

Keyboard Navigation

API Reference

SearchInput

Accessibility

Keyboard Navigation

With keyboard navigation

Notes

Controlled & Uncontrolled

Keyboard Callbacks

Custom Prefix

Size Variants

Invalid & Disabled

Source

View component source (12 files)