# SearchInput

**📖 Live documentation:** https://cds.coinbase.com/components/inputs/SearchInput/

A control for searching a dataset.

## Import

```tsx
import { SearchInput } from '@coinbase/cds-web/controls/SearchInput'
```

## Examples

### Basic usage

```tsx live
function BasicSearchInput() {
  const [value, setValue] = useState('');
  return (
    <VStack gap={2}>
      <SearchInput
        value={value}
        onChangeText={setValue}
        onClear={() => setValue('')}
        onSearch={(searchTerm) => console.log('Searching for:', searchTerm)}
        placeholder="Search..."
      />
      <Text color="foregroundMuted" font="caption">
        Press Enter to trigger search
      </Text>
    </VStack>
  );
}
```

### Variants

When `bordered={false}`, SearchInput keeps focused border styling disabled by default. Set
`focusedBorderWidth` to opt into a focus border style.

```tsx live
function SearchInputVariants() {
  const [value1, setValue1] = useState('');
  const [value2, setValue2] = useState('');
  const [value3, setValue3] = useState('');
  const [value4, setValue4] = useState('');

  return (
    <VStack gap={2}>
      <SearchInput
        value={value1}
        onChangeText={setValue1}
        onClear={() => setValue1('')}
        placeholder="Compact search..."
        compact
      />
      <SearchInput
        value={value2}
        onChangeText={setValue2}
        onClear={() => setValue2('')}
        placeholder="Borderless search (default focus behavior)..."
        bordered={false}
      />
      <SearchInput
        value={value3}
        onChangeText={setValue3}
        onClear={() => setValue3('')}
        placeholder="Borderless search (with focus border)..."
        bordered={false}
        focusedBorderWidth={200}
      />
      <SearchInput
        value={value4}
        onChangeText={setValue4}
        onClear={() => setValue4('')}
        placeholder="No icons..."
        hideStartIcon
        hideEndIcon
      />
    </VStack>
  );
}
```

### With Custom End Element

```tsx live
function CustomEndSearchInput() {
  const [value, setValue] = useState('');
  return (
    <SearchInput
      value={value}
      onChangeText={setValue}
      onClear={() => setValue('')}
      placeholder="Custom end element..."
      end={<InputIconButton name="filter" onClick={() => console.log('Filter clicked')} />}
    />
  );
}
```

## Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `onChangeText` | `(text: string) => void` | Yes | `-` | - |
| `align` | `center \| start \| end \| justify` | No | `start` | Text Align Input |
| `alignContent` | `ResponsiveProp<center \| normal \| start \| end \| flex-start \| flex-end \| stretch \| baseline \| first baseline \| last baseline \| space-between \| space-around \| space-evenly>` | No | `-` | - |
| `alignItems` | `ResponsiveProp<center \| normal \| start \| end \| flex-start \| flex-end \| self-start \| self-end \| stretch \| baseline \| first baseline \| last baseline>` | No | `-` | - |
| `alignSelf` | `ResponsiveProp<center \| normal \| auto \| start \| end \| flex-start \| flex-end \| self-start \| self-end \| stretch \| baseline \| first baseline \| last baseline>` | No | `-` | - |
| `as` | `input` | No | `-` | The underlying element or component the polymorphic component will render.  Changing as also changes the inherited native props (e.g. href for as=a) and the expected ref type. |
| `aspectRatio` | `ResponsiveProp<AspectRatio>` | No | `-` | - |
| `background` | `ResponsiveProp<Color>` | No | `-` | - |
| `borderBottomLeftRadius` | `ResponsiveProp<BorderRadius>` | No | `-` | - |
| `borderBottomRightRadius` | `ResponsiveProp<BorderRadius>` | No | `-` | - |
| `borderBottomWidth` | `ResponsiveProp<BorderWidth>` | No | `-` | - |
| `borderColor` | `ResponsiveProp<Color>` | No | `-` | - |
| `borderEndWidth` | `ResponsiveProp<BorderWidth>` | No | `-` | - |
| `borderRadius` | `ResponsiveProp<BorderRadius>` | No | `200` | Leverage one of the borderRadius styles we offer to round the corners of the input. |
| `borderStartWidth` | `ResponsiveProp<BorderWidth>` | No | `-` | - |
| `borderTopLeftRadius` | `ResponsiveProp<BorderRadius>` | No | `-` | - |
| `borderTopRightRadius` | `ResponsiveProp<BorderRadius>` | No | `-` | - |
| `borderTopWidth` | `ResponsiveProp<BorderWidth>` | No | `-` | - |
| `borderWidth` | `ResponsiveProp<BorderWidth>` | No | `-` | - |
| `bordered` | `boolean` | No | `true` | Add a border around all sides of the box. Adds border to input. When set to false, focus border styling is disabled by default. |
| `borderedBottom` | `boolean` | No | `-` | Add a border to the bottom side of the box. |
| `borderedEnd` | `boolean` | No | `-` | Add a border to the trailing side of the box. |
| `borderedHorizontal` | `boolean` | No | `-` | Add a border to the leading and trailing sides of the box. |
| `borderedStart` | `boolean` | No | `-` | Add a border to the leading side of the box. |
| `borderedTop` | `boolean` | No | `-` | Add a border to the top side of the box. |
| `borderedVertical` | `boolean` | No | `-` | Add a border to the top and bottom sides of the box. |
| `bottom` | `ResponsiveProp<Bottom<string \| number>>` | No | `-` | - |
| `clearIconAccessibilityLabel` | `string` | No | `-` | Set the a11y label for the clear icon |
| `color` | `ResponsiveProp<Color>` | No | `-` | - |
| `columnGap` | `ResponsiveProp<Space>` | No | `-` | - |
| `compact` | `boolean` | No | `false` | Enables compact variation |
| `containerSpacing` | `string` | No | `-` | Custom container spacing if needed. This will add to the existing spacing |
| `dangerouslySetBackground` | `string` | No | `-` | - |
| `disabled` | `boolean` | No | `false` | Toggles input interactability and opacity |
| `display` | `ResponsiveProp<grid \| revert \| none \| block \| inline \| inline-block \| flex \| inline-flex \| inline-grid \| contents \| flow-root \| list-item>` | No | `-` | - |
| `elevation` | `ResponsiveProp<Elevation>` | No | `-` | - |
| `enableColorSurge` | `boolean` | No | `-` | Enable Color Surge motion |
| `end` | `ReactNode` | No | `-` | Set the end node Adds content to the end of the inner input. Refer to diagram for location of endNode in InputStack component |
| `flexBasis` | `ResponsiveProp<FlexBasis<string \| number>>` | No | `-` | - |
| `flexDirection` | `ResponsiveProp<column \| row \| row-reverse \| column-reverse>` | No | `-` | - |
| `flexGrow` | `ResponsiveProp<FlexGrow>` | No | `-` | - |
| `flexShrink` | `ResponsiveProp<FlexShrink>` | No | `-` | - |
| `flexWrap` | `ResponsiveProp<nowrap \| wrap \| wrap-reverse>` | No | `-` | - |
| `focusedBorderWidth` | `BorderWidth` | No | `-` | Additional border width when focused. Set this when bordered={false} to opt into a focus border style. |
| `font` | `ResponsiveProp<FontFamily \| inherit>` | No | `-` | - |
| `fontFamily` | `ResponsiveProp<FontFamily \| inherit>` | No | `-` | - |
| `fontSize` | `ResponsiveProp<FontSize \| inherit>` | No | `-` | - |
| `fontWeight` | `ResponsiveProp<FontWeight \| inherit>` | No | `-` | - |
| `gap` | `ResponsiveProp<Space>` | No | `-` | - |
| `grid` | `ResponsiveProp<Grid>` | No | `-` | - |
| `gridArea` | `ResponsiveProp<GridArea>` | No | `-` | - |
| `gridAutoColumns` | `ResponsiveProp<GridAutoColumns<string \| number>>` | No | `-` | - |
| `gridAutoFlow` | `ResponsiveProp<GridAutoFlow>` | No | `-` | - |
| `gridAutoRows` | `ResponsiveProp<GridAutoRows<string \| number>>` | No | `-` | - |
| `gridColumn` | `ResponsiveProp<GridColumn>` | No | `-` | - |
| `gridColumnEnd` | `ResponsiveProp<GridColumnEnd>` | No | `-` | - |
| `gridColumnStart` | `ResponsiveProp<GridColumnStart>` | No | `-` | - |
| `gridRow` | `ResponsiveProp<GridRow>` | No | `-` | - |
| `gridRowEnd` | `ResponsiveProp<GridRowEnd>` | No | `-` | - |
| `gridRowStart` | `ResponsiveProp<GridRowStart>` | No | `-` | - |
| `gridTemplate` | `ResponsiveProp<GridTemplate>` | No | `-` | - |
| `gridTemplateAreas` | `ResponsiveProp<GridTemplateAreas>` | No | `-` | - |
| `gridTemplateColumns` | `ResponsiveProp<GridTemplateColumns<string \| number>>` | No | `-` | - |
| `gridTemplateRows` | `ResponsiveProp<GridTemplateRows<string \| number>>` | No | `-` | - |
| `height` | `ResponsiveProp<Height<string \| number>>` | No | `-` | Height of input |
| `helperText` | `ReactNode` | No | `-` | For cases where label is not enough information to describe what the text input is for. Can also be used for showing positive/negative messages |
| `helperTextErrorIconAccessibilityLabel` | `string` | No | `'error'` | Accessibility label for helper text error icon when variant=negative |
| `hideEndIcon` | `boolean` | No | `-` | hide the end icon |
| `hideStartIcon` | `boolean` | No | `false` | hide the start icon |
| `inputBackground` | `Color` | No | `'bg'` | Background color of the input. |
| `inputNode` | `ReactElement` | No | `-` | Customize the element which the input area will be rendered as. Adds ability to render the input area as a <textarea />, <input /> etc... By default, the input area will be rendered as an <input />. |
| `justifyContent` | `ResponsiveProp<left \| right \| center \| normal \| start \| end \| flex-start \| flex-end \| stretch \| space-between \| space-around \| space-evenly>` | No | `-` | - |
| `key` | `Key \| null` | No | `-` | - |
| `label` | `string` | No | `-` | Short messageArea indicating purpose of input |
| `labelNode` | `ReactNode` | No | `-` | React node to render label. Takes precedence over label. |
| `labelVariant` | `inside \| outside` | No | `'outside'` | The variant of the label. Only used when compact is not true. |
| `left` | `ResponsiveProp<Left<string \| number>>` | No | `-` | - |
| `lineHeight` | `ResponsiveProp<LineHeight \| inherit>` | No | `-` | - |
| `margin` | `ResponsiveProp<0 \| -5 \| -10 \| -0.25 \| -0.5 \| -0.75 \| -1 \| -1.5 \| -2 \| -3 \| -4 \| -6 \| -7 \| -8 \| -9>` | No | `-` | - |
| `marginBottom` | `ResponsiveProp<0 \| -5 \| -10 \| -0.25 \| -0.5 \| -0.75 \| -1 \| -1.5 \| -2 \| -3 \| -4 \| -6 \| -7 \| -8 \| -9>` | No | `-` | - |
| `marginEnd` | `ResponsiveProp<0 \| -5 \| -10 \| -0.25 \| -0.5 \| -0.75 \| -1 \| -1.5 \| -2 \| -3 \| -4 \| -6 \| -7 \| -8 \| -9>` | No | `-` | - |
| `marginStart` | `ResponsiveProp<0 \| -5 \| -10 \| -0.25 \| -0.5 \| -0.75 \| -1 \| -1.5 \| -2 \| -3 \| -4 \| -6 \| -7 \| -8 \| -9>` | No | `-` | - |
| `marginTop` | `ResponsiveProp<0 \| -5 \| -10 \| -0.25 \| -0.5 \| -0.75 \| -1 \| -1.5 \| -2 \| -3 \| -4 \| -6 \| -7 \| -8 \| -9>` | No | `-` | - |
| `marginX` | `ResponsiveProp<0 \| -5 \| -10 \| -0.25 \| -0.5 \| -0.75 \| -1 \| -1.5 \| -2 \| -3 \| -4 \| -6 \| -7 \| -8 \| -9>` | No | `-` | - |
| `marginY` | `ResponsiveProp<0 \| -5 \| -10 \| -0.25 \| -0.5 \| -0.75 \| -1 \| -1.5 \| -2 \| -3 \| -4 \| -6 \| -7 \| -8 \| -9>` | No | `-` | - |
| `maxHeight` | `ResponsiveProp<MaxHeight<string \| number>>` | No | `-` | - |
| `maxWidth` | `ResponsiveProp<MaxWidth<string \| number>>` | No | `-` | - |
| `minHeight` | `ResponsiveProp<MinHeight<string \| number>>` | No | `-` | - |
| `minWidth` | `ResponsiveProp<MinWidth<string \| number>>` | No | `-` | - |
| `onChange` | `FormEventHandler<HTMLDivElement>` | No | `-` | - |
| `onClear` | `MouseEventHandler<Element>` | No | `-` | - |
| `onSearch` | `((str: string) => void)` | No | `-` | Callback is fired when a user hits enter on the keyboard. Can obtain the query through str parameter |
| `opacity` | `ResponsiveProp<Opacity>` | No | `-` | - |
| `overflow` | `ResponsiveProp<hidden \| auto \| visible \| clip \| scroll>` | No | `-` | - |
| `padding` | `ResponsiveProp<Space>` | No | `-` | - |
| `paddingBottom` | `ResponsiveProp<Space>` | No | `-` | - |
| `paddingEnd` | `ResponsiveProp<Space>` | No | `-` | - |
| `paddingStart` | `ResponsiveProp<Space>` | No | `-` | - |
| `paddingTop` | `ResponsiveProp<Space>` | No | `-` | - |
| `paddingX` | `ResponsiveProp<Space>` | No | `-` | - |
| `paddingY` | `ResponsiveProp<Space>` | No | `-` | - |
| `pin` | `PinningDirection` | No | `-` | Direction in which to absolutely pin the box. |
| `placeholder` | `string` | No | `-` | Placeholder text displayed inside of the input. Will be replaced if there is a value. |
| `position` | `ResponsiveProp<fixed \| static \| relative \| absolute \| sticky>` | No | `-` | - |
| `ref` | `((instance: HTMLInputElement \| null) => void) \| RefObject<HTMLInputElement> \| null` | No | `-` | - |
| `right` | `ResponsiveProp<Right<string \| number>>` | No | `-` | - |
| `rowGap` | `ResponsiveProp<Space>` | No | `-` | - |
| `start` | `ReactNode` | No | `-` | Adds content to the start of the inner input. Refer to diagram for location of startNode in InputStack component |
| `startIcon` | `search \| backArrow` | No | `search` | Set the start icon. You can only set it to search \| backArrow icon. If you set this, the icon would not toggle between search and backArrow depending on the focus state |
| `startIconAccessibilityLabel` | `string` | No | `-` | Set the a11y label for the start icon |
| `style` | `CSSProperties` | No | `-` | - |
| `suffix` | `string` | No | `-` | Adds suffix text to the end of input |
| `testID` | `string` | No | `-` | Used to locate this element in unit and end-to-end tests. Under the hood, testID translates to data-testid on Web. On Mobile, testID stays the same - testID |
| `testIDMap` | `{ start?: string; end?: string \| undefined; label?: string \| undefined; helperText?: string \| undefined; } \| undefined` | No | `-` | Add ability to test individual parts of the input |
| `textAlign` | `ResponsiveProp<center \| start \| end \| justify>` | No | `-` | - |
| `textDecoration` | `ResponsiveProp<none \| underline \| overline \| line-through \| underline overline \| underline double>` | No | `-` | - |
| `textTransform` | `ResponsiveProp<capitalize \| lowercase \| none \| uppercase>` | No | `-` | - |
| `top` | `ResponsiveProp<Top<string \| number>>` | No | `-` | - |
| `transform` | `ResponsiveProp<Transform>` | No | `-` | - |
| `type` | `button \| reset \| submit` | No | `-` | - |
| `userSelect` | `ResponsiveProp<text \| none \| auto \| all>` | No | `-` | - |
| `value` | `string \| number \| readonly string[]` | No | `-` | - |
| `variant` | `InputVariant` | No | `foregroundMuted` | Determines the sentiment of the input. Because we allow startContent and endContent to be custom ReactNode, the content placed inside these slots will not change colors according to the variant. You will have to add that yourself |
| `visibility` | `ResponsiveProp<hidden \| visible>` | No | `-` | - |
| `width` | `ResponsiveProp<Width<string \| number>>` | No | `100%` | Width of input as a percentage string. |
| `zIndex` | `ResponsiveProp<ZIndex>` | No | `-` | - |