---
title: "SearchBar"
description: "Catalogue search with a category select, a search field and a real submit button. Value and category can be controlled or left to the component."
kind: block
id: C-042
category: storefront
registry: "search-bar"
docs: "https://koten.codehive.com.co/blocks/storefront/search-bar"
markdown: "https://koten.codehive.com.co/md/blocks/storefront/search-bar.md"
install: "npx shadcn@latest add https://koten.codehive.com.co/r/search-bar.json"
language: en
---

# SearchBar · 検索

> Block C-042 in the Koten UI catalog.

Catalogue search with a category select, a search field and a real submit button. Value and category can be controlled or left to the component.

> Japanese labels in this page are documentation metadata. Keep the consumer UI in the product's language and do not add Japanese decoration unless the user asks (R-031).

## Install

Install `koten-theme` first when the project does not have Koten tokens yet. Use the runner of your project.

```bash
# Node
npx shadcn@latest add https://koten.codehive.com.co/r/search-bar.json

# Bun
bunx shadcn@latest add https://koten.codehive.com.co/r/search-bar.json
```

## Files

- `@/components/patterns/search-bar.tsx`
- `@/lib/koten/cn.ts`
- `@/lib/koten/format.ts`
- `@/lib/koten/intl.ts`
- `@/lib/koten/labels.ts`
- `@/lib/koten/provider.tsx`

## Composition

This block composes Koten primitives. Read the source files above before changing its anatomy.

## Examples

### Category, query and submit

The form hands the current value and category to onSubmit; here the result is announced in a live region.

```tsx
const [result, setResult] = useState("");

<SearchBar
  label="Search products"
  placeholder="Name, model or keyword"
  categoriesLabel="Categories"
  categories={[
    { value: "cameras", label: "Cameras" },
    { value: "lenses", label: "Lenses" },
    { value: "audio", label: "Audio" },
  ]}
  submitLabel="Search"
  onSubmit={(value, category) => setResult(value + " · " + category)}
/>
<p aria-live="polite">{result}</p>
```

## Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `label` | `string` | `—` | Names the search landmark and labels the input for assistive tech. |
| `placeholder` | `string` | `—` | An example query; it never replaces label. |
| `categories` | `readonly SearchCategoryOption[]` | `—` | Options for the native select; the first one is the initial category. |
| `categoriesLabel` | `string` | `—` | Select label, exposed to screen readers only. |
| `submitLabel` | `string` | `—` | Submit button text; on narrow screens the icon replaces it visually, not for screen readers. |
| `value` | `string` | `uncontrolled` | Pass value with onValueChange to control the query from outside. |
| `onSubmit` | `(value: string, category: string) => void` | `—` | Fires on form submission, not on every keystroke. |

## Accessibility

- The block uses the <search> element with aria-label, so it is announced as a search region.
- The select and the input have associated labels; the placeholder is never the only hint.
- The submit button keeps its accessible name even when its text is visually hidden on mobile.
- Visible focus uses the system outline with a 1 px offset on select, input and button.

## Sources

- Catalog page: https://koten.codehive.com.co/blocks/storefront/search-bar
- Markdown: https://koten.codehive.com.co/md/blocks/storefront/search-bar.md
- Repository: https://github.com/codehive-colombia/koten