# SearchInput

A search input provides a specialized text field for search functionality, featuring a search icon and optional clear button. It's optimized for search queries and includes built-in state management for search field behavior.

## When to Use

- Enable users to search through large datasets or content
- Provide filtering capabilities in lists, tables, or catalogs
- Create search bars for navigation or content discovery
- Implement autocomplete or suggestion functionality
- Offer quick search access in headers or sidebars

## Component

---

### Properties

- **`value`** `string` — The search value in controlled mode
- **`defaultValue`** `string` — The default search value in uncontrolled mode
- **`placeholder`** `string` — Placeholder text when input is empty
- **`icon`** `ReactElement` — Icon element rendered before the input (default: search icon)
- **`prefix`** `ReactNode` — Content rendered before the input
- **`suffix`** — Input decoration after the main input (before clear button)
- **`suffixPosition`** `'before' | 'after'` (default: `after`) — Position of suffix relative to validation/loading state icons
- **`isClearable`** `boolean` (default: `false`) — Whether the search input shows a clear button
- **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — Input size
- **`autocomplete`** `string` — HTML autocomplete attribute for browser autofill behavior
- **`inputProps`** `Props` — Direct props passed to the native input element
- **`wrapperProps`** `Props` — Direct props passed to the input wrapper element
- **`onChange`** `function` — Callback fired when the search value changes
- **`onSubmit`** `function` — Callback fired when search is submitted
- **`onClear`** `function` — Callback fired when search is cleared
- **`onBlur`** `function` — Callback fired when the input loses focus
- **`onFocus`** `function` — Callback fired when the input receives focus

### Base Properties

Supports [Base properties](../../BaseProperties.md)

### Field Properties

Supports all [Field properties](../../FieldProperties.md)

### Styling Properties

#### styles

Customizes the root wrapper element of the component.

**Sub-elements:**
- `Prefix` - Element displayed before the input (contains search icon)
- `Suffix` - Element displayed after the input (contains clear button when shown)
- `State` - Container for validation state indicators
- `InputIcon` - Icon displayed within the input area
- `ValidationIcon` - Icon displayed for validation state

#### inputStyles

Customizes the search input field specifically.

### Style Properties

These properties allow direct style application without using the `styles` prop:

- **Base:** `display`, `font`, `preset`, `hide`, `whiteSpace`, `opacity`, `transition`
- **Position:** `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position`
- **Dimension:** `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
- **Block:** `border`, `radius`, `shadow`, `outline`, `padding`, `paddingInline`, `paddingBlock`, `overflow`, `scrollbar`, `textAlign`
- **Color:** `color`, `fill`, `fade`, `image`

### Modifiers

The `mods` property accepts the following modifiers you can override:

- **`focused`** `boolean` — Whether the input has focus
- **`disabled`** `boolean` — Whether the search input is disabled
- **`invalid`** `boolean` — Whether the search input has validation errors
- **`valid`** `boolean` — Whether the search input is valid
- **`hovered`** `boolean` — Whether the search input is being hovered
- **`inside-form`** `boolean` — Whether the search input is inside a form field

## Variants

### Sizes

- `small` - Compact size for dense interfaces
- `medium` - Standard size
- `large` - Emphasized size for prominent search functionality

## Examples

### Basic Usage

```jsx
<SearchInput
  label="Search"
  placeholder="Search products..."
/>
```

### With Clear Button

```jsx
<SearchInput
  label="Filter items"
  placeholder="Type to filter..."
  isClearable={true}
/>
```

### Controlled Search

```jsx
const [searchValue, setSearchValue] = useState('');

<SearchInput
  label="Search"
  value={searchValue}
  onChange={setSearchValue}
  placeholder="Search content..."
/>
```

### With Description

```jsx
<SearchInput
  label="Search Library"
  description="Search by title, author, or ISBN"
  placeholder="Enter search terms..."
/>
```

### Small Size

```jsx
<SearchInput
  size="small"
  placeholder="Quick search..."
  aria-label="Quick search"
/>
```

### With Validation

```jsx
<SearchInput
  label="Search Query"
  validationState="invalid"
  errorMessage="Search query too short"
  placeholder="Enter at least 3 characters"
/>
```

### Disabled State

```jsx
<SearchInput
  label="Search (Offline)"
  isDisabled
  placeholder="Search unavailable"
/>
```

### With Custom Suffix

```jsx
<SearchInput
  label="Advanced Search"
  placeholder="Search with filters..."
  suffix={<FilterButton />}
/>
```

## Accessibility

### Keyboard Navigation

- `Tab` - Moves focus to the search input
- `Escape` - Clears the search input (when `isClearable` is true)
- `Enter` - Submits search or triggers onSubmit callback
- All standard text input keyboard shortcuts work for text entry

### Screen Reader Support

- Component announces as "search" input type to screen readers
- Search icon and clear button have appropriate labels
- Current search value and results count are announced when available
- Loading states and validation errors are communicated

### ARIA Properties

- `aria-label` - Provides accessible label when no visible label exists
- `aria-labelledby` - References external label elements
- `aria-describedby` - References additional descriptive text
- `aria-invalid` - Indicates validation state
- `role="searchbox"` - Identifies the input as a search field
- Clear button includes appropriate `aria-label`

## Best Practices

1. **Do**: Provide clear placeholder text indicating what can be searched
   ```jsx
   <SearchInput placeholder="Search by name, email, or department..." />
   ```

2. **Don't**: Use search input for non-search related text entry
   ```jsx
   <SearchInput label="Enter your name" /> {/* Use TextInput instead */}
   ```

3. **Performance**: Debounce search queries to avoid excessive API calls
4. **UX**: Show search results or feedback immediately when possible
5. **Accessibility**: Always provide meaningful labels or aria-label
6. **Clear**: Enable clear functionality for better user experience

## Integration with Forms

This component supports all [Field properties](../../FieldProperties.md) when used within a Form.

## Suggested Improvements

- Add built-in debouncing for search queries
- Implement search suggestions or autocomplete dropdown
- Add search history or recent searches functionality
- Include advanced search filters integration
- Add keyboard shortcuts for common search actions

## Related Components

- [TextInput](./TextInput.md) - For general text input
- [ComboBox](./ComboBox.md) - For searchable selection with predefined options
- [Select](./Select.md) - For selection without search functionality
