# Search

An input that allows users to find content by entering a search term.

Tabs: [Guidelines](/components/web/search/search.guidelines.md) · [Code](/components/web/search/search.code.md)

## Basic usage

`Search` is a controlled component. Pass the current query as `value` and update it from `onValueChange`, which receives the next value as a string (an empty string when the field is cleared).

```tsx
import {useState} from 'react'
import {Search} from '@pleo-io/telescope'

const EmployeeSearch = () => {
    const [query, setQuery] = useState('')

    return <Search label="Search employees" value={query} onValueChange={setQuery} />
}
```

The `label` is rendered as a visually hidden `<label>`, so screen readers announce what the field searches. The component is wrapped in a `role="search"` landmark.

## Placeholder

When no `placeholder` is passed, `Search` uses the localised default from the `TelescopeProvider` translations (`Search.Placeholder`). Pass `placeholder` to override it for a specific context.

```tsx
<Search
    label="Search employees"
    placeholder="Find a person"
    value={query}
    onValueChange={setQuery}
/>
```

## Other props

`Search` also accepts the `Input` props (except `variant`, `prefix`, `postfix` and `type`) and the native `input` props, for example `disabled`, `id` and `onChange`. `onChange` is still called alongside `onValueChange`.

## Localisation

The default placeholder is read from the `TelescopeProvider` translations as `Search.Placeholder`.

## API reference

#### `disabled`

Type: `boolean`

Default: -

Makes the input disabled if true

#### `innerRef`

Type: `RefObject<HTMLInputElement | null> | undefined`

##### Allowed values

- `RefObject<HTMLInputElement | null>`

Default: -

A ref that points to the input

#### `isInvalid`

Type: `boolean`

Default: -

A boolean flag that shows the input in an error state if true.

#### `isRequired`

Type: `boolean`

Default: -

Adds aria-required="true" to the input

#### `label` (required)

Type: `string`

Default: `''`

Label to be used for VisuallyHidden label

#### `name`

Type: `string | undefined`

Default: -

The name of the input

#### `onValueChange`

Type: `((value: string) => void) | undefined`

##### Allowed values

- `(value: string) => void`

Default: `noop`

Callback called with the string representation of the next value No value will be returned as an empty string

#### `renderError`

Type: `(() => ReactNode) | undefined`

##### Allowed values

- `() => ReactNode`

Default: -

Render prop for error message

#### `renderInput`

Type: `((ariaProps: AriaProps, inputProps: InputHTMLAttributes<HTMLInputElement>) => any) | undefined`

##### Allowed values

- `(ariaProps: AriaProps, inputProps: InputHTMLAttributes<HTMLInputElement>) => any`

Default: -

Render prop for input component. Provides user with access to ariaProps and inputProps, a whitelisted set of props for the input

#### `skeleton`

Type: `boolean`

Default: `false`

Show a skeleton loading state

#### `value` (required)

Type: `string`

Default: `''`

The current value of the search query