Component reference
SearchInput
Filter a documentation list with controlled search text.
Preview
Live previewOptional six-digit hex. Clear to restore the preset. Check contrast with your brand color.
Changes apply to this preview only.
Search the documentation
Results filter as you type. Enter records the query; Escape clears the field.
Install the workspace, build the generated tokens and start the playground.
Try a preset, a colour mode, a brand colour, a radius and a density.
A search field with a keyboard hint, a clear action and Enter to submit.
Documentation samples with line numbers, highlights and copy feedback.
Primitive colours, spacing and radii feeding the semantic theme aliases.
Width adapts to the available space
"use client";
import { useState } from "react";
import {
Card,
CardHeader,
CardTitle,
CardDescription,
CardContent,
SearchInput,
Badge
} from "@pimolu/react";
const docEntries = [
{
title: "Installation",
section: "Getting started",
excerpt: "Install the workspace, build the generated tokens and start the playground.",
},
{
title: "Theme builder",
section: "Design system",
excerpt: "Try a preset, a colour mode, a brand colour, a radius and a density.",
},
{
title: "SearchInput",
section: "Forms",
excerpt: "A search field with a keyboard hint, a clear action and Enter to submit.",
},
{
title: "CodeBlock",
section: "Typography",
excerpt: "Documentation samples with line numbers, highlights and copy feedback.",
},
{
title: "Design tokens",
section: "Design system",
excerpt: "Primitive colours, spacing and radii feeding the semantic theme aliases.",
},
];
function DocumentationSearch() {
const [query, setQuery] = useState("");
const [submitted, setSubmitted] = useState<string | null>(null);
const normalized = query.trim().toLowerCase();
const results = normalized
? docEntries.filter((entry) => `${entry.title} ${entry.section} ${entry.excerpt}`
.toLowerCase()
.includes(normalized))
: docEntries;
return (
<Card>
<CardHeader>
<CardTitle>Search the documentation</CardTitle>
<CardDescription>
Results filter as you type. Enter records the query; Escape
clears the field.
</CardDescription>
</CardHeader>
<CardContent>
<div className="grid gap-5 min-w-0">
<SearchInput
label="Search the documentation"
placeholder="Search components, tokens, guides…"
shortcut="/"
value={query}
onValueChange={(nextValue: string) => {
setQuery(nextValue);
if(!nextValue)
setSubmitted(null);
}}
onSearch={(nextValue: string) => setSubmitted(nextValue)}
/>
<div className="flex flex-wrap items-center gap-3 min-w-0 justify-between">
<span className="text-sm text-muted leading-relaxed">
{results.length} result
{results.length === 1 ? "" : "s"}
</span>
{
submitted !== null && (<Badge
variant="primary"
appearance="soft"
size="sm"
>
Searched: {submitted || "everything"}
</Badge>)
}
</div>
<div className="grid gap-5 min-w-0">
{
results.map((entry) => (<Card key={entry.title} size="sm">
<CardContent>
<div
className="flex flex-wrap items-center gap-3 min-w-0 justify-between"
>
<strong>{entry.title}</strong>
<Badge variant="neutral" appearance="soft" size="sm">
{entry.section}
</Badge>
</div>
<p className="text-sm text-muted leading-relaxed">
{entry.excerpt}
</p>
</CardContent>
</Card>))
}
{
results.length === 0 && (<p
className="text-sm text-muted leading-relaxed"
>
No page matches “{query}”. Try a component name
or a token.
</p>)
}
</div>
</div>
</CardContent>
</Card>
);
}
export function DemoExample() {
return (<DocumentationSearch />);
}More examples
Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.
Basic
The shortcut is rendered as a Kbd; it is a hint, not a global key binding.
Sizes
sm, md and lg reuse the Input height and type scale.
Controlled and states
A controlled field follows its value; disabled, non-clearable and custom clear labels are supported.
Usage
Keep the query and result set synchronized, including the clear action.
API reference
Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.
PimoluSearchInputProps
Type source| Name | Type | Default | Description |
|---|---|---|---|
value | string | undefined | — | Controlled query. |
defaultValue | string | undefined | — | Initial query when uncontrolled. |
onValueChange | ((value: string) => void) | undefined | — | Called with every next query, including clear and Escape. |
onSearch | ((value: string) => void) | undefined | — | Called with the current query when Enter is pressed. |
placeholder | string | undefined | "Search…" | Placeholder text. Defaults to "Search…". |
shortcut | string | undefined | — | Keyboard hint rendered as a Kbd, for example "/" or "⌘K". |
clearable | boolean | undefined | true | Show the accessible clear button. Defaults to true. |
clearLabel | string | undefined | "Clear search" | Accessible name for the clear button. |
size | "sm" | "md" | "lg" | undefined | "md" | Height and type scale. Defaults to "md". |
label | string | undefined | — | Visible label, also used as the accessible name. |
aria-label | string | undefined | — | Accessible name when no visible label is supplied. |
aria-describedby | string | undefined | — | Additional accessible description. |
disabled | boolean | undefined | false | Disable the field and its actions. |
className | string | undefined | — | Class applied to the outer wrapper. |
name | string | undefined | — | Native input name, useful inside a form. |
autoComplete | string | undefined | — | Forwarded to the native input. |
autoFocus | boolean | undefined | — | Focus the field on mount. |
id | string | undefined | — | Native input id, when an external label points at it. |
valuestring | undefinedNo default extracted.
Controlled query.
defaultValuestring | undefinedNo default extracted.
Initial query when uncontrolled.
onValueChange((value: string) => void) | undefinedNo default extracted.
Called with every next query, including clear and Escape.
onSearch((value: string) => void) | undefinedNo default extracted.
Called with the current query when Enter is pressed.
placeholderstring | undefinedDefault: "Search…"
Placeholder text. Defaults to "Search…".
shortcutstring | undefinedNo default extracted.
Keyboard hint rendered as a Kbd, for example "/" or "⌘K".
clearableboolean | undefinedDefault: true
Show the accessible clear button. Defaults to true.
clearLabelstring | undefinedDefault: "Clear search"
Accessible name for the clear button.
size"sm" | "md" | "lg" | undefinedDefault: "md"
Height and type scale. Defaults to "md".
labelstring | undefinedNo default extracted.
Visible label, also used as the accessible name.
aria-labelstring | undefinedNo default extracted.
Accessible name when no visible label is supplied.
aria-describedbystring | undefinedNo default extracted.
Additional accessible description.
disabledboolean | undefinedDefault: false
Disable the field and its actions.
classNamestring | undefinedNo default extracted.
Class applied to the outer wrapper.
namestring | undefinedNo default extracted.
Native input name, useful inside a form.
autoCompletestring | undefinedNo default extracted.
Forwarded to the native input.
autoFocusboolean | undefinedNo default extracted.
Focus the field on mount.
idstring | undefinedNo default extracted.
Native input id, when an external label points at it.
Accessibility
- Label search and expose result feedback without announcing every keystroke assertively.