Search Bar - CometChat Docs

AI Integration Quick Reference

{
  "component": "CometChatSearchBar",
  "package": "@cometchat/chat-uikit-react",
  "import": "import { CometChatSearchBar } from \"@cometchat/chat-uikit-react\";",
  "cssImport": "import \"@cometchat/chat-uikit-react/css-variables.css\";",
  "description": "A reusable search input with icon, clear button, debounce support, and full keyboard accessibility.",
  "cssRootClass": ".cometchat-search-bar",
  "subComponents": ["Root", "Icon", "Input", "ClearButton"],
  "props": {
    "Root": {
      "value": { "type": "string", "default": "undefined", "note": "Controlled mode." },
      "defaultValue": { "type": "string", "default": "\"\"", "note": "Uncontrolled mode." },
      "onChange": { "type": "(value: string) => void", "default": "undefined" },
      "placeholder": { "type": "string", "default": "\"Search\"" },
      "disabled": { "type": "boolean", "default": "false" },
      "debounceMs": { "type": "number", "default": "0" },
      "inputRef": { "type": "Ref<HTMLInputElement>", "default": "undefined" },
      "className": { "type": "string", "default": "undefined" },
      "style": { "type": "CSSProperties", "default": "undefined" },
      "children": { "type": "ReactNode", "default": "undefined" }
    },
    "Icon": {
      "icon": { "type": "ReactNode", "default": "built-in search icon" },
      "className": { "type": "string", "default": "undefined" }
    },
    "Input": {
      "className": { "type": "string", "default": "undefined" },
      "...rest": { "type": "InputHTMLAttributes", "default": "undefined", "note": "Forwarded to the native <input>." }
    },
    "ClearButton": {
      "icon": { "type": "ReactNode", "default": "built-in × icon" },
      "className": { "type": "string", "default": "undefined" },
      "aria-label": { "type": "string", "default": "\"Clear search\"" }
    }
  },
  "types": {
    "CometChatSearchBarRootProps": "See Props section",
    "CometChatSearchBarIconProps": "See Props section",
    "CometChatSearchBarInputProps": "See Props section",
    "CometChatSearchBarClearButtonProps": "See Props section",
    "CometChatSearchBarContextValue": {
      "value": "string",
      "setValue": "(value: string) => void",
      "clear": "() => void",
      "placeholder": "string",
      "disabled": "boolean",
      "inputId": "string"
    }
  }
}

Where It Fits

CometChatSearchBar is a base component used inside feature components like CometChatConversations, CometChatUsers, and CometChatGroups to provide search and filter functionality. It renders a search icon, a text input, and an optional clear button. Wire it into any list component to enable filtering.

import { CometChatSearchBar } from "@cometchat/chat-uikit-react";
import "@cometchat/chat-uikit-react/css-variables.css";
import { useState } from "react";

function ConversationsPanel() {
  const [query, setQuery] = useState("");

  return (
    <div style={{ width: 360, padding: 16 }}>
      <CometChatSearchBar.Root value={query} onChange={setQuery} placeholder="Search conversations...">
        <CometChatSearchBar.Icon />
        <CometChatSearchBar.Input />
        <CometChatSearchBar.ClearButton />
      </CometChatSearchBar.Root>
      {/* CometChatConversations.List would go here, filtered by query */}
    </div>
  );
}

Minimal Render

import { CometChatSearchBar } from "@cometchat/chat-uikit-react";
import "@cometchat/chat-uikit-react/css-variables.css";

function Demo() {
  return (
    <CometChatSearchBar.Root>
      <CometChatSearchBar.Icon />
      <CometChatSearchBar.Input />
    </CometChatSearchBar.Root>
  );
}

Root CSS class: .cometchat-search-bar

Sub-Components

CometChatSearchBar is a compound component with four sub-components:

Sub-component	Purpose
`Root`	Container that provides context, manages state, and supports controlled/uncontrolled modes with optional debounce.
`Icon`	Decorative search icon. Hidden from assistive technology.
`Input`	The `<input>` element with `role="searchbox"`, `aria-label`, and Escape-to-clear.
`ClearButton`	Clear/reset button. Only visible and focusable when the input has a value.

Root

The outermost wrapper. Manages search state and provides it to child sub-components via React context. Supports controlled mode (value + onChange), uncontrolled mode (defaultValue), and optional debounce.

<CometChatSearchBar.Root value={query} onChange={setQuery} debounceMs={300}>
  {/* Icon, Input, ClearButton go here */}
</CometChatSearchBar.Root>

Icon

Renders the search icon. Decorative by default (aria-hidden="true"). Pass a custom icon prop to replace the built-in icon.

<CometChatSearchBar.Icon />
<CometChatSearchBar.Icon icon={<span>🔍</span>} />

Input

The text input. Reads value, placeholder, and disabled from context. Supports Escape key to clear. Forwards additional HTML input attributes like autoFocus and maxLength.

<CometChatSearchBar.Input autoFocus maxLength={100} />

ClearButton

A button that clears the search value. Hidden from the tab order when the input is empty. Pass a custom icon prop to replace the default × icon.

<CometChatSearchBar.ClearButton />
<CometChatSearchBar.ClearButton icon={<span>✕</span>} aria-label="Reset" />

Actions and Events

Callback Props

onChange

Fires when the search value changes. Receives the new value as a plain string.

import { CometChatSearchBar } from "@cometchat/chat-uikit-react";
import "@cometchat/chat-uikit-react/css-variables.css";
import { useState } from "react";

function SearchExample() {
  const [query, setQuery] = useState("");

  return (
    <CometChatSearchBar.Root value={query} onChange={setQuery}>
      <CometChatSearchBar.Icon />
      <CometChatSearchBar.Input />
      <CometChatSearchBar.ClearButton />
    </CometChatSearchBar.Root>
  );
}

Custom View Slots

Slot	Prop	Signature	Replaces
Search icon	`Icon.icon`	`ReactNode`	Built-in CSS mask search icon
Clear icon	`ClearButton.icon`	`ReactNode`	Built-in CSS mask × icon

Custom search icon

TypeScript
CSS

import { CometChatSearchBar } from "@cometchat/chat-uikit-react";
import "@cometchat/chat-uikit-react/css-variables.css";

function CustomIconSearch() {
  return (
    <CometChatSearchBar.Root placeholder="Search...">
      <CometChatSearchBar.Icon icon={<img src="/my-search-icon.svg" alt="" width={20} height={20} />} />
      <CometChatSearchBar.Input />
      <CometChatSearchBar.ClearButton icon={<span style={{ fontSize: 14, color: "#999" }}>✕</span>} />
    </CometChatSearchBar.Root>
  );
}

App.css

/* No CSS overrides needed — icons are replaced via props */

Common Patterns

Debounced search

Prevent excessive API calls during rapid typing by setting debounceMs.

import { CometChatSearchBar } from "@cometchat/chat-uikit-react";
import "@cometchat/chat-uikit-react/css-variables.css";

function DebouncedSearch({ onSearch }: { onSearch: (q: string) => void }) {
  return (
    <CometChatSearchBar.Root onChange={onSearch} debounceMs={300} placeholder="Search users...">
      <CometChatSearchBar.Icon />
      <CometChatSearchBar.Input />
      <CometChatSearchBar.ClearButton />
    </CometChatSearchBar.Root>
  );
}

Controlled vs uncontrolled

Controlled mode gives you full control over the value. Uncontrolled mode lets the component manage its own state.

import { CometChatSearchBar } from "@cometchat/chat-uikit-react";
import "@cometchat/chat-uikit-react/css-variables.css";
import { useState } from "react";

// Controlled
function ControlledSearch() {
  const [query, setQuery] = useState("");
  return (
    <CometChatSearchBar.Root value={query} onChange={setQuery}>
      <CometChatSearchBar.Icon />
      <CometChatSearchBar.Input />
      <CometChatSearchBar.ClearButton />
    </CometChatSearchBar.Root>
  );
}

// Uncontrolled
function UncontrolledSearch() {
  return (
    <CometChatSearchBar.Root defaultValue="" onChange={(v) => console.log(v)}>
      <CometChatSearchBar.Icon />
      <CometChatSearchBar.Input />
    </CometChatSearchBar.Root>
  );
}

Without clear button

Just don’t render the ClearButton sub-component.

<CometChatSearchBar.Root onChange={handleSearch}>
  <CometChatSearchBar.Icon />
  <CometChatSearchBar.Input />
</CometChatSearchBar.Root>

Key	Behavior
`Tab`	Moves focus to the input, then to the clear button (if visible), then out
`Shift+Tab`	Reverse focus order
`Escape`	Clears the input value and keeps focus on the input
`Enter`	No default action (consumers can attach `onKeyDown` for submit behavior)

The clear button is only in the tab order when the input has a non-empty value. When the input is empty, the clear button has tabIndex={-1}. The input itself does not show a focus outline — the container’s pill shape provides sufficient visual context.

CSS Architecture

The component uses CSS custom properties (design tokens) defined in @cometchat/chat-uikit-react/css-variables.css. The cascade:

Global tokens set on the .cometchat root wrapper.
Component CSS (.cometchat-search-bar) consumes these tokens via var().
Overrides target .cometchat-search-bar descendant selectors.

Key Selectors

Target	Selector
Root container	`.cometchat-search-bar`
Search icon	`.cometchat-search-bar__icon`
Input	`.cometchat-search-bar__input`
Input placeholder	`.cometchat-search-bar__input::placeholder`
Clear button	`.cometchat-search-bar__clear-button`
Clear button icon	`.cometchat-search-bar__clear-button-icon`
Disabled state	`.cometchat-search-bar--disabled`

Example: Brand-themed search bar

App.css

.cometchat-search-bar {
  border-color: var(--brand-border);
  background: var(--brand-surface);
}

.cometchat-search-bar__icon {
  background: var(--brand-icon);
}

.cometchat-search-bar__input:focus-visible {
  outline-color: var(--brand-primary);
}

Customization Matrix

What to change	Where	Property/API	Example
Search value	Component props	`value`, `onChange` on `Root`	`<Root value={q} onChange={setQ}>`
Placeholder text	Component props	`placeholder` on `Root`	`<Root placeholder="Find...">`
Debounce delay	Component props	`debounceMs` on `Root`	`<Root debounceMs={300}>`
Disable interaction	Component props	`disabled` on `Root`	`<Root disabled>`
Replace search icon	Component props	`icon` on `Icon`	`<Icon icon={<MyIcon />}>`
Replace clear icon	Component props	`icon` on `ClearButton`	`<ClearButton icon={<X />}>`
Hide clear button	Composition	Omit `ClearButton`	Don’t render `<ClearButton />`
Change visual styling	Global CSS	`.cometchat-search-bar` selectors	See example above

Props

All props are optional unless noted otherwise.

CometChatSearchBar.Root

value

Current search value. When provided, the component operates in controlled mode.


Type	`string`
Default	`undefined`

defaultValue

Initial search value for uncontrolled mode. Ignored when value is provided.


Type	`string`
Default	`""`

onChange

Callback fired when the search value changes. Receives the new value as a plain string.


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

placeholder

Placeholder text for the input.


Type	`string`
Default	`"Search"`

disabled

Whether the search bar is disabled. Propagated to the input and clear button via context.


Type	`boolean`
Default	`false`

debounceMs

Debounce delay in milliseconds for the onChange callback. Set to 0 for no debounce.


Type	`number`
Default	`0`

inputRef

Ref forwarded to the underlying <input> element. Convenience prop — equivalent to using a ref on the Input sub-component directly.


Type	`Ref<HTMLInputElement>`
Default	`undefined`

className

Custom CSS class appended to the root container.


Type	`string`
Default	`undefined`

style

Custom inline styles for the root container.


Type	`CSSProperties`
Default	`undefined`

children

Content rendered inside the root. Typically Icon, Input, and ClearButton sub-components.


Type	`ReactNode`
Default	`undefined`

CometChatSearchBar.Icon

icon

Custom icon element. Defaults to the built-in CSS mask search icon.


Type	`ReactNode`
Default	Built-in search icon

className

Custom CSS class appended to the icon container.


Type	`string`
Default	`undefined`

CometChatSearchBar.Input

className

Custom CSS class appended to the input element.


Type	`string`
Default	`undefined`

…rest

All standard HTML input attributes (except value, onChange, disabled, placeholder which are managed by context) are forwarded to the native <input> element.


Type	`InputHTMLAttributes<HTMLInputElement>`
Default	—

CometChatSearchBar.ClearButton

icon

Custom clear icon element. Defaults to the built-in CSS mask × icon.


Type	`ReactNode`
Default	Built-in × icon

className

Custom CSS class appended to the clear button.


Type	`string`
Default	`undefined`

aria-label

Accessible label for the clear button.


Type	`string`
Default	`"Clear search"`

CSS Selectors

Target	Selector
Root	`.cometchat-search-bar`
Search icon	`.cometchat-search-bar__icon`
Input	`.cometchat-search-bar__input`
Input placeholder	`.cometchat-search-bar__input::placeholder`
Clear button	`.cometchat-search-bar__clear-button`
Clear button icon	`.cometchat-search-bar__clear-button-icon`
Disabled modifier	`.cometchat-search-bar--disabled`

Documentation Index

​Where It Fits

​Minimal Render

​Sub-Components

​Root

​Icon

​Input

​ClearButton

​Actions and Events

​Callback Props

​onChange

​Custom View Slots

​Custom search icon

​Common Patterns

​Debounced search

​Controlled vs uncontrolled

​Without clear button

​Keyboard Navigation

​CSS Architecture

​Key Selectors

​Example: Brand-themed search bar

​Customization Matrix

​Props

​CometChatSearchBar.Root

​value

​defaultValue

​onChange

​placeholder

​disabled

​debounceMs

​inputRef

​className

​style

​children

​CometChatSearchBar.Icon

​icon

​className

​CometChatSearchBar.Input

​className

​…rest

​CometChatSearchBar.ClearButton

​icon

​className

​aria-label

​CSS Selectors

Where It Fits

Minimal Render

Sub-Components

Root

Icon

Input

ClearButton

Actions and Events

Callback Props

onChange

Custom View Slots

Custom search icon

Common Patterns

Debounced search

Controlled vs uncontrolled

Without clear button

Keyboard Navigation

CSS Architecture

Key Selectors

Example: Brand-themed search bar

Customization Matrix

Props

CometChatSearchBar.Root

value

defaultValue

onChange

placeholder

disabled

debounceMs

inputRef

className

style

children

CometChatSearchBar.Icon

icon

className

CometChatSearchBar.Input

className

…rest

CometChatSearchBar.ClearButton

icon

className

aria-label

CSS Selectors