

<InteractiveDemo
  name="search-field"
  controls="[
  {
    type: &#x22;string&#x22;,
    name: &#x22;label&#x22;,
    defaultValue: &#x22;Search&#x22;,
  },
  {
    type: &#x22;string&#x22;,
    name: &#x22;description&#x22;,
    defaultValue: &#x22;&#x22;,
    placeholder: &#x22;Helper text&#x22;,
  },
  {
    type: &#x22;string&#x22;,
    name: &#x22;placeholder&#x22;,
    defaultValue: &#x22;Search...&#x22;,
  },
  {
    type: &#x22;enum&#x22;,
    name: &#x22;size&#x22;,
    options: [&#x22;sm&#x22;, &#x22;md&#x22;, &#x22;lg&#x22;],
    defaultValue: &#x22;md&#x22;,
  },
  {
    type: &#x22;boolean&#x22;,
    name: &#x22;isDisabled&#x22;,
    defaultValue: false,
  },
  {
    type: &#x22;boolean&#x22;,
    name: &#x22;isReadOnly&#x22;,
    defaultValue: false,
  },
  {
    type: &#x22;boolean&#x22;,
    name: &#x22;isInvalid&#x22;,
    defaultValue: false,
  },
]"
/>

## Installation [#installation]

<InstallPrerequisite>
  Before adding components, init your project with your design system from the [Studio](/studio).
</InstallPrerequisite>

<CodeBlockTabs defaultValue="npm" groupId="package-manager">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npx shadcn@latest add @dotui/search-field
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest add @dotui/search-field
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn dlx shadcn@latest add @dotui/search-field
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bunx shadcn@latest add @dotui/search-field
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## Usage [#usage]

```tsx
import { SearchField } from "@/components/ui/search-field"
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/field"
```

```tsx
<SearchField>
  <Label>Search</Label>
  <Input />
</SearchField>
```

## Anatomy [#anatomy]

A `SearchField` wraps an optional `Label`, an `Input`, and optional `Description` and `FieldError`. Rendered on its own it supplies a default `InputGroup` with a search icon and a clear button, so `<SearchField><Input /></SearchField>` is enough.

```tsx
import { SearchField } from "@/components/ui/search-field"
import { Label, Description, FieldError } from "@/components/ui/field"
import { Input } from "@/components/ui/input"
```

```tsx
<SearchField>
  <Label />
  <Input />
  <Description />
  <FieldError />
</SearchField>
```

## Value [#value]

The value is a string. Use `defaultValue` for uncontrolled state, or `value` with `onChange` to control it.

```tsx
const [value, setValue] = React.useState('')

<SearchField value={value} onChange={setValue}>
  <Label>Search</Label>
  <Input />
</SearchField>
```

## Submit & clear [#submit--clear]

`onSubmit` fires with the current value when the user presses <kbd>Enter</kbd>; `onClear` fires when they press <kbd>Escape</kbd> or the clear button, which appears once the field is non-empty.

```tsx
<SearchField onSubmit={(value) => search(value)} onClear={() => reset()}>
  <Label>Search</Label>
  <Input />
</SearchField>
```

## Examples [#examples]

<Examples className="sm:grid-cols-2">
  <Example name="search-field/demos/default" title="Basic Search" />

  <Example name="search-field/demos/with-suggestions" title="Search with Suggestions" />

  <Example name="search-field/demos/header-search" title="Header Search" />

  <Example name="search-field/demos/filterable-list" title="Search with Filtered Results" className="col-span-full" />
</Examples>

## API Reference [#api-reference]

<Reference name="search-field" />
