Dropdown

Base selection element for choosing a single option from a collapsible list, with full keyboard navigation and ARIA compliance.

AI Integration Quick Reference

{
  "component": "CometChatDropdown",
  "package": "@cometchat/chat-uikit-react",
  "import": "import { CometChatDropdown } from \"@cometchat/chat-uikit-react\";",
  "cssImport": "import \"@cometchat/chat-uikit-react/css-variables.css\";",
  "description": "Base selection element for choosing a single option from a collapsible list, with full keyboard navigation and ARIA compliance.",
  "cssRootClass": ".cometchat-dropdown",
  "primaryOutput": {
    "prop": "onSelect",
    "type": "(option: CometChatDropdownOption) => void"
  },
  "props": {
    "data": {
      "options": { "type": "CometChatDropdownOption[]", "default": "required", "note": "Array of selectable options" },
      "placeholder": { "type": "string", "default": "\"Select...\"" },
      "defaultValue": { "type": "string", "default": "undefined", "note": "id of the pre-selected option" },
      "disabled": { "type": "boolean", "default": "false" }
    },
    "callbacks": {
      "onSelect": "(option: CometChatDropdownOption) => void"
    }
  },
  "events": [],
  "sdkListeners": [],
  "types": {
    "CometChatDropdownOption": {
      "id": "string",
      "label": "string"
    }
  }
}

Where It Fits

CometChatDropdown is a base element used wherever the UI needs a single-selection input from a predefined list. It appears inside components like CometChatChangeScope (selecting a group member’s role) and custom forms. It replaces native <select> elements with a styled, keyboard-accessible alternative that follows the UIKit’s design tokens.

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

function RoleSelector() {
  const roles = [
    { id: "participant", label: "Participant" },
    { id: "moderator", label: "Moderator" },
    { id: "admin", label: "Admin" },
  ];

  return (
    <CometChatDropdown
      options={roles}
      placeholder="Select role"
      onSelect={(option) => console.log("Selected:", option.label)}
    />
  );
}

---

Minimal Render

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

function DropdownDemo() {
  return (
    <CometChatDropdown
      options={[
        { id: "1", label: "Option 1" },
        { id: "2", label: "Option 2" },
      ]}
      onSelect={(option) => console.log(option)}
    />
  );
}

export default DropdownDemo;

Root CSS class: .cometchat-dropdown

---

Actions and Events

Callback Props

onSelect

Fires when the user selects an option from the list. The payload is the full option object ({ id, label }).

import { CometChatDropdown } from "@cometchat/chat-uikit-react";

function DropdownWithHandler() {
  return (
    <CometChatDropdown
      options={[
        { id: "light", label: "Light" },
        { id: "dark", label: "Dark" },
      ]}
      onSelect={(option) => {
        console.log("Selected theme:", option.id);
      }}
    />
  );
}

Selection can be triggered by:

• Clicking an option
• Pressing Enter on a focused option
• Pressing ArrowDown / ArrowUp to navigate, then Enter to confirm

---

Common Patterns

Pre-selected value

Use defaultValue to set an initially selected option by its id.

import { CometChatDropdown } from "@cometchat/chat-uikit-react";

function PreselectedDropdown() {
  const options = [
    { id: "en", label: "English" },
    { id: "fr", label: "French" },
    { id: "es", label: "Spanish" },
  ];

  return (
    <CometChatDropdown
      options={options}
      defaultValue="fr"
      onSelect={(option) => console.log(option.label)}
    />
  );
}

Disabled dropdown

import { CometChatDropdown } from "@cometchat/chat-uikit-react";

function DisabledDropdown() {
  return (
    <CometChatDropdown
      options={[{ id: "1", label: "Locked" }]}
      defaultValue="1"
      disabled
      onSelect={() => {}}
    />
  );
}

Keyboard navigation

The dropdown supports full keyboard operation:

Key	Behavior
Enter / Space	Opens the dropdown when the trigger is focused; selects the highlighted option when the list is open
ArrowDown	Moves highlight to the next option (wraps to first when at the end)
ArrowUp	Moves highlight to the previous option (wraps to last when at the start)
Escape	Closes the dropdown and returns focus to the trigger
Home	Moves highlight to the first option
End	Moves highlight to the last option

---

CSS Architecture

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

1. Global tokens set on the .cometchat root wrapper.
2. Component CSS (.cometchat-dropdown) consumes these tokens via var().
3. Overrides target .cometchat-dropdown descendant selectors.

Key Selectors

Target	Selector
Root	.cometchat-dropdown
Trigger button	.cometchat-dropdown__trigger
Placeholder text	.cometchat-dropdown__placeholder
Selected value text	.cometchat-dropdown__value
Arrow icon	.cometchat-dropdown__arrow
Options list	.cometchat-dropdown__listbox
Individual option	.cometchat-dropdown__option
Highlighted option	.cometchat-dropdown__option--highlighted
Selected option	.cometchat-dropdown__option--selected
Disabled state	.cometchat-dropdown--disabled
Open state	.cometchat-dropdown--open

Example: Custom border and option highlight

.cometchat .cometchat-dropdown .cometchat-dropdown__trigger {
  border-radius: 8px;
  border: 2px solid var(--cometchat-border-color-light);
}

.cometchat .cometchat-dropdown .cometchat-dropdown__option--highlighted {
  background-color: var(--cometchat-primary-color);
  color: #fff;
}

Customization Matrix

What to change	Where	Property/API	Example
Handle selection	Component props	onSelect callback	onSelect={(opt) => ...}
Set initial selection	Component props	defaultValue	defaultValue="admin"
Change placeholder text	Component props	placeholder	placeholder="Choose..."
Disable interaction	Component props	disabled	disabled={true}
Change colors, border	Global CSS	.cometchat-dropdown selectors	See example above

---

Props

---

options (required)

Array of selectable options. Each option must have a unique id and a display label.

Type	CometChatDropdownOption[]
Default	—

interface CometChatDropdownOption {
  id: string;
  label: string;
}

---

onSelect (required)

Callback fired when the user selects an option.

Type	(option: CometChatDropdownOption) => void
Default	—

---

placeholder

Text displayed when no option is selected.

Type	string
Default	"Select..."

---

defaultValue

The id of the option that should be selected on first render.

Type	string
Default	undefined

---

disabled

Disables the dropdown. Prevents opening and selection.

Type	boolean
Default	false

---

className

Custom CSS class applied to the root element.

Type	string
Default	undefined

---

Events

This component does not emit custom DOM events. All interactions are handled via the onSelect callback prop.

---

CSS Selectors

Target	Selector
Root	.cometchat-dropdown
Open state root	.cometchat-dropdown--open
Disabled state root	.cometchat-dropdown--disabled
Trigger button	.cometchat-dropdown__trigger
Trigger focus ring	.cometchat-dropdown__trigger:focus-visible
Placeholder text	.cometchat-dropdown__placeholder
Selected value text	.cometchat-dropdown__value
Arrow icon	.cometchat-dropdown__arrow
Arrow rotated (open)	.cometchat-dropdown--open .cometchat-dropdown__arrow
Options listbox	.cometchat-dropdown__listbox
Individual option	.cometchat-dropdown__option
Highlighted option (keyboard)	.cometchat-dropdown__option--highlighted
Selected option	.cometchat-dropdown__option--selected
Option hover	.cometchat-dropdown__option:hover