SearchInput

SearchInput

SearchInput is a small controlled wrapper around Carbon's Search component. It is intended for straightforward text search fields where the parent owns the input value and may optionally trigger a search action when the user presses Enter.

Overview

The component keeps the API intentionally narrow:

• controlled value plus onChange
• optional onSearch callback for Enter
• built-in clear support through Carbon's clear button
• blur deduplication so the same value is not emitted twice

Internally, the component tracks the last emitted value with a ref. That matters because pressing Enter blurs the field. Without that guard, Carbon's blur event could trigger a duplicate onChange after the latest typed value had already been emitted.

Props

Name	Type	Required	Description
id	string	Yes	Unique identifier passed to Carbon and used as the rendered data-testid.
label	string	Yes	Accessible label forwarded to Carbon as labelText.
placeholder	string	Yes	Placeholder text shown in the input and also used as the control's aria-label.
value	string	Yes	Current controlled value.
onChange	(value: string) => void	Yes	Called whenever the component emits a new value through typing, clearing, or blur reconciliation.
onSearch	() => void	No	Optional callback fired when the user presses Enter.

Behavior

Typing

Typing calls onChange with the current text on each input change. The component does not debounce or fetch suggestions. If you need async suggestions, use AutoCompleteInput instead.

Clear button

The built-in Carbon clear button calls onChange('').

Blur handling

On blur, the component compares the DOM value with the last value already emitted through onChange.

• if the value is unchanged, nothing else happens
• if the value differs, it emits the latest value once

This avoids duplicate updates during Enter-to-search flows.

Enter key

When the user presses Enter:

1. the input is blurred
2. blur reconciliation runs if needed
3. onSearch() is called when provided

This means Enter behaves like a commit action without requiring the parent to listen to keyboard events directly.

Usage

import { useState } from "react";

import SearchInput from "@/components/Form/SearchInput";

export function UserSearch() {
  const [search, setSearch] = useState("");

  const handleSearch = () => {
    // Trigger API call or local filtering.
  };

  return (
    <SearchInput
      id="user-search"
      label="Search users"
      placeholder="Search by name"
      value={search}
      onChange={setSearch}
      onSearch={handleSearch}
    />
  );
}

Accessibility Notes

• renders with role="searchbox"
• exposes the placeholder text as the aria-label
• provides a labeled clear button through closeButtonLabelText="Clear search input"

Testing Notes

The unit tests cover the main contract:

• accessible rendering
• controlled updates while typing
• Enter-triggered search behavior
• no duplicate onChange emission on blur after the latest value has already been emitted
• correct handling when onSearch is omitted

When To Use

Use SearchInput when you need a simple controlled search box.

Use AutoCompleteInput instead when the field must fetch suggestions, debounce requests, or manage selectable result items.