Emoji Keyboard - CometChat Docs

AI Integration Quick Reference

{
  "component": "CometChatEmojiKeyboard",
  "package": "@cometchat/chat-uikit-react",
  "import": "import { CometChatEmojiKeyboard } from \"@cometchat/chat-uikit-react\";",
  "cssImport": "import \"@cometchat/chat-uikit-react/css-variables.css\";",
  "description": "A categorized emoji picker with search, category tabs, and full keyboard accessibility.",
  "cssRootClass": ".cometchat-emoji-keyboard",
  "subComponents": ["Root", "CategoryTabs", "SearchBar", "EmojiGrid", "CategorySection", "EmptyState"],
  "lazyLoaded": true,
  "props": {
    "Root": {
      "emojiData": { "type": "CometChatEmojiKeyboardCategoryData[]", "default": "built-in dataset" },
      "onEmojiClick": { "type": "(emoji: string) => void", "default": "undefined" },
      "onClose": { "type": "() => void", "default": "undefined" },
      "className": { "type": "string", "default": "undefined" },
      "children": { "type": "ReactNode", "default": "undefined", "note": "When omitted, renders default layout." }
    },
    "CategoryTabs": {
      "className": { "type": "string", "default": "undefined" }
    },
    "SearchBar": {
      "placeholder": { "type": "string", "default": "localized 'Search emoji'" },
      "className": { "type": "string", "default": "undefined" }
    },
    "EmojiGrid": {
      "emojis": { "type": "Record<string, CometChatEmojiKeyboardEmojiData>", "default": "required" },
      "className": { "type": "string", "default": "undefined" }
    },
    "CategorySection": {
      "category": { "type": "CometChatEmojiKeyboardCategoryData", "default": "required" },
      "className": { "type": "string", "default": "undefined" }
    },
    "EmptyState": {
      "children": { "type": "ReactNode", "default": "'No emojis found'" },
      "className": { "type": "string", "default": "undefined" }
    }
  },
  "types": {
    "CometChatEmojiKeyboardEmojiData": { "char": "string", "keywords": "string[]" },
    "CometChatEmojiKeyboardCategoryData": { "id": "string", "name": "string", "symbolURL": "string?", "emojis": "Record<string, CometChatEmojiKeyboardEmojiData>" }
  }
}

Where It Fits

CometChatEmojiKeyboard is a base component used by the message composer to let users browse and select emojis. It displays categorized emojis in a grid with a search bar and category tabs. It is lazy-loaded via React.lazy() since it is only rendered when the user opens the emoji picker.

import React, { Suspense, lazy, useState } from "react";
import "@cometchat/chat-uikit-react/css-variables.css";

const CometChatEmojiKeyboard = lazy(() =>
  import("@cometchat/chat-uikit-react").then((m) => ({
    default: m.CometChatEmojiKeyboard.Root,
  }))
);

function ComposerWithEmoji() {
  const [showPicker, setShowPicker] = useState(false);
  const [message, setMessage] = useState("");

  return (
    <div style={{ position: "relative", width: 400 }}>
      <input
        value={message}
        onChange={(e) => setMessage(e.target.value)}
        placeholder="Type a message..."
        style={{ width: "100%", padding: 8 }}
      />
      <button onClick={() => setShowPicker(!showPicker)}>😀</button>
      {showPicker && (
        <Suspense fallback={<div>Loading...</div>}>
          <CometChatEmojiKeyboard
            onEmojiClick={(emoji) => {
              setMessage((prev) => prev + emoji);
              setShowPicker(false);
            }}
            onClose={() => setShowPicker(false)}
          />
        </Suspense>
      )}
    </div>
  );
}

Minimal Render

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

function Demo() {
  return (
    <CometChatEmojiKeyboard.Root
      onEmojiClick={(emoji) => console.log("Selected:", emoji)}
    />
  );
}

Root CSS class: .cometchat-emoji-keyboard

Sub-Components

CometChatEmojiKeyboard is a compound component with six sub-components:

Sub-component	Purpose
`Root`	Container that provides context, manages state, and renders default layout when no children are provided.
`CategoryTabs`	Horizontal scrollable tab bar for emoji categories. Follows WAI-ARIA Tabs pattern.
`SearchBar`	Search input for filtering emojis. Wraps `CometChatSearchBar`.
`EmojiGrid`	Grid of emoji buttons with arrow key navigation. Uses `role="grid"`.
`CategorySection`	A category title + emoji grid pair.
`EmptyState`	Shown when search yields no results. Uses `aria-live="polite"`.

Root

The outermost wrapper. Manages emoji data, search state, and active category. When no children are provided, it renders the default layout (SearchBar + CategoryTabs + category sections + EmptyState).

<CometChatEmojiKeyboard.Root
  onEmojiClick={(emoji) => console.log(emoji)}
  onClose={() => console.log("closed")}
/>

CategoryTabs

Renders a horizontal scrollable tab bar with one tab per emoji category. Supports mouse wheel horizontal scrolling and full keyboard navigation (ArrowLeft/ArrowRight, Home/End).

<CometChatEmojiKeyboard.Root>
  <CometChatEmojiKeyboard.SearchBar />
  <CometChatEmojiKeyboard.CategoryTabs />
</CometChatEmojiKeyboard.Root>

SearchBar

Wraps CometChatSearchBar and wires it to the emoji keyboard context. Filters emojis by keyword as the user types.

<CometChatEmojiKeyboard.SearchBar placeholder="Find an emoji..." />

EmojiGrid

Renders emojis in an 8-column grid with full arrow key navigation. Each emoji is a <button> with role="gridcell" and aria-label.

<CometChatEmojiKeyboard.EmojiGrid
  emojis={{ smile: { char: "😄", keywords: ["happy"] } }}
/>

EmptyState

Shown when search yields no results. Uses aria-live="polite" to announce the empty state to screen readers.

<CometChatEmojiKeyboard.EmptyState>
  No emojis match your search
</CometChatEmojiKeyboard.EmptyState>

Actions and Events

Callback Props

onEmojiClick

Fires when the user clicks or presses Enter on an emoji. Receives the emoji character as a string.

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

function EmojiPicker() {
  return (
    <CometChatEmojiKeyboard.Root
      onEmojiClick={(emoji) => {
        console.log("Selected emoji:", emoji);
      }}
    />
  );
}

onClose

Fires when the user presses Escape (and search is empty). Use this to close the emoji picker popover.

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

function ToggleablePicker() {
  const [open, setOpen] = useState(true);

  if (!open) return <button onClick={() => setOpen(true)}>Open Picker</button>;

  return (
    <CometChatEmojiKeyboard.Root
      onEmojiClick={(emoji) => console.log(emoji)}
      onClose={() => setOpen(false)}
    />
  );
}

Custom View Slots

Slot	Prop	Signature	Replaces
Custom emoji data	`Root.emojiData`	`CometChatEmojiKeyboardCategoryData[]`	Built-in emoji dataset
Empty state content	`EmptyState.children`	`ReactNode`	Default “No emojis found” text

Custom emoji data

Provide your own emoji categories and emojis instead of the built-in dataset.

TypeScript
CSS

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

const customEmojis: CometChatEmojiKeyboardCategoryData[] = [
  {
    id: "favorites",
    name: "Favorites",
    emojis: {
      thumbsup: { char: "👍", keywords: ["thumb", "up", "approve"] },
      heart: { char: "❤️", keywords: ["love", "heart", "red"] },
      fire: { char: "🔥", keywords: ["fire", "hot", "lit"] },
      rocket: { char: "🚀", keywords: ["rocket", "launch", "fast"] },
    },
  },
];

function CustomPicker() {
  return (
    <CometChatEmojiKeyboard.Root
      emojiData={customEmojis}
      onEmojiClick={(emoji) => console.log(emoji)}
    />
  );
}

App.css

/* No CSS overrides needed — custom data uses the same grid layout */

Common Patterns

Lazy-loaded emoji picker

Since the emoji keyboard is a heavy component (~1,800 emojis), lazy-load it to keep the initial bundle small.

import React, { Suspense, lazy, useState } from "react";
import "@cometchat/chat-uikit-react/css-variables.css";

const EmojiKeyboardRoot = lazy(() =>
  import("@cometchat/chat-uikit-react").then((m) => ({
    default: m.CometChatEmojiKeyboard.Root,
  }))
);

function LazyEmojiPicker({ onSelect }: { onSelect: (emoji: string) => void }) {
  const [open, setOpen] = useState(false);

  return (
    <>
      <button onClick={() => setOpen(!open)}>😀</button>
      {open && (
        <Suspense fallback={<div style={{ width: 320, height: 380 }}>Loading...</div>}>
          <EmojiKeyboardRoot
            onEmojiClick={(emoji) => {
              onSelect(emoji);
              setOpen(false);
            }}
            onClose={() => setOpen(false)}
          />
        </Suspense>
      )}
    </>
  );
}

Compound composition

Render only the sub-components you need. For example, show just the search bar and category tabs without the default grid layout.

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

function MinimalPicker() {
  return (
    <CometChatEmojiKeyboard.Root onEmojiClick={console.log}>
      <CometChatEmojiKeyboard.SearchBar />
      <CometChatEmojiKeyboard.CategoryTabs />
    </CometChatEmojiKeyboard.Root>
  );
}

Key	Context	Behavior
`Tab`	Any	Move focus between sections: search → tabs → emoji grid
`Shift+Tab`	Any	Move focus backwards between sections
`ArrowLeft` / `ArrowRight`	Category tabs	Navigate between tabs
`Home` / `End`	Category tabs	Jump to first / last tab
`Enter` / `Space`	Category tab	Activate the focused tab and scroll to that category
`ArrowUp` / `ArrowDown` / `ArrowLeft` / `ArrowRight`	Emoji grid	Navigate the emoji grid
`Home` / `End`	Emoji grid	Jump to first / last emoji
`Enter` / `Space`	Emoji grid	Select the focused emoji
`Escape`	Search input	Clear the search query
`Escape`	Any (search empty)	Signal close to parent via `onClose`
`/`	Any (not in input)	Focus the search input

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-emoji-keyboard) consumes these tokens via var().
Overrides target .cometchat-emoji-keyboard descendant selectors.

Key Selectors

Target	Selector
Root	`.cometchat-emoji-keyboard`
Search wrapper	`.cometchat-emoji-keyboard__search`
Category tabs	`.cometchat-emoji-keyboard__tabs`
Single tab	`.cometchat-emoji-keyboard__tab`
Active tab	`.cometchat-emoji-keyboard__tab--active`
Tab icon	`.cometchat-emoji-keyboard__tab-icon`
Emoji list	`.cometchat-emoji-keyboard__list`
Category title	`.cometchat-emoji-keyboard__category-title`
Emoji grid	`.cometchat-emoji-keyboard__emoji-grid`
Emoji item	`.cometchat-emoji-keyboard__emoji-item`
Empty state	`.cometchat-emoji-keyboard__empty-state`

Example: Brand-themed emoji keyboard

App.css

.cometchat-emoji-keyboard {
  --cometchat-emoji-keyboard-width: 360px;
  --cometchat-emoji-keyboard-height: 420px;
  --cometchat-emoji-keyboard-border-radius: 16px;
}

.cometchat-emoji-keyboard__tab--active {
  background: var(--brand-primary-light);
}

.cometchat-emoji-keyboard__tab--active .cometchat-emoji-keyboard__tab-icon {
  background-color: var(--brand-primary);
}

Customization Matrix

What to change	Where	Property/API	Example
Emoji dataset	Component props	`emojiData` on `Root`	`<Root emojiData={custom}>`
Handle selection	Component props	`onEmojiClick` on `Root`	`<Root onEmojiClick={fn}>`
Handle close	Component props	`onClose` on `Root`	`<Root onClose={fn}>`
Search placeholder	Component props	`placeholder` on `SearchBar`	`<SearchBar placeholder="Find...">`
Empty state content	Composition	`EmptyState.children`	`<EmptyState>Custom text</EmptyState>`
Hide search bar	Composition	Omit `SearchBar`	Use children without `<SearchBar />`
Hide category tabs	Composition	Omit `CategoryTabs`	Use children without `<CategoryTabs />`
Change dimensions	CSS	`--cometchat-emoji-keyboard-width/height`	See example above
Change visual styling	Global CSS	`.cometchat-emoji-keyboard` selectors	See example above

Props

All props are optional unless noted otherwise.

CometChatEmojiKeyboard.Root

emojiData

Custom emoji categories. When omitted, the built-in dataset (~1,800 emojis across 8 categories) is used.


Type	`CometChatEmojiKeyboardCategoryData[]`
Default	Built-in emoji dataset

interface CometChatEmojiKeyboardCategoryData {
  id: string;
  name: string;
  symbolURL?: string;
  emojis: Record<string, CometChatEmojiKeyboardEmojiData>;
}

interface CometChatEmojiKeyboardEmojiData {
  char: string;
  keywords: string[];
}

onEmojiClick

Callback fired when an emoji is selected (click or Enter key).


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

onClose

Callback fired when Escape is pressed and search is empty. Use this to close the picker.


Type	`() => void`
Default	`undefined`

className

Custom CSS class appended to the root container.


Type	`string`
Default	`undefined`

children

Sub-components to render. When omitted, Root renders the default layout (SearchBar + CategoryTabs + category sections + EmptyState).


Type	`ReactNode`
Default	`undefined`

CometChatEmojiKeyboard.CategoryTabs

className

Custom CSS class appended to the tabs container.


Type	`string`
Default	`undefined`

CometChatEmojiKeyboard.SearchBar

placeholder

Placeholder text for the search input.


Type	`string`
Default	Localized “Search emoji”

className

Custom CSS class appended to the search wrapper.


Type	`string`
Default	`undefined`

CometChatEmojiKeyboard.EmojiGrid

emojis

Emojis to render in the grid. Required.


Type	`Record<string, CometChatEmojiKeyboardEmojiData>`
Default	—

className

Custom CSS class appended to the grid container.


Type	`string`
Default	`undefined`

CometChatEmojiKeyboard.CategorySection


Type	`CometChatEmojiKeyboardCategoryData`
Default	—

className

Custom CSS class appended to the section container.


Type	`string`
Default	`undefined`

CometChatEmojiKeyboard.EmptyState

children

Custom empty state content.


Type	`ReactNode`
Default	`"No emojis found"`

className

Custom CSS class appended to the empty state container.


Type	`string`
Default	`undefined`

CSS Selectors

Target	Selector
Root	`.cometchat-emoji-keyboard`
Search wrapper	`.cometchat-emoji-keyboard__search`
Category tabs container	`.cometchat-emoji-keyboard__tabs`
Single tab	`.cometchat-emoji-keyboard__tab`
Active tab modifier	`.cometchat-emoji-keyboard__tab--active`
Tab icon (SVG mask)	`.cometchat-emoji-keyboard__tab-icon`
Tab emoji fallback	`.cometchat-emoji-keyboard__tab-emoji`
Emoji list container	`.cometchat-emoji-keyboard__list`
Category section	`.cometchat-emoji-keyboard__category-section`
Category title	`.cometchat-emoji-keyboard__category-title`
Emoji grid	`.cometchat-emoji-keyboard__emoji-grid`
Emoji item	`.cometchat-emoji-keyboard__emoji-item`
Empty state	`.cometchat-emoji-keyboard__empty-state`

Documentation Index

​Where It Fits

​Minimal Render

​Sub-Components

​Root

​CategoryTabs

​SearchBar

​EmojiGrid

​EmptyState

​Actions and Events

​Callback Props

​onEmojiClick

​onClose

​Custom View Slots

​Custom emoji data

​Common Patterns

​Lazy-loaded emoji picker

​Compound composition

​Keyboard Navigation

​CSS Architecture

​Key Selectors

​Example: Brand-themed emoji keyboard

​Customization Matrix

​Props

​CometChatEmojiKeyboard.Root

​emojiData

​onEmojiClick

​onClose

​className

​children

​CometChatEmojiKeyboard.CategoryTabs

​className

​CometChatEmojiKeyboard.SearchBar

​placeholder

​className

​CometChatEmojiKeyboard.EmojiGrid

​emojis

​className

​CometChatEmojiKeyboard.CategorySection

​category

​className

​CometChatEmojiKeyboard.EmptyState

​children

​className

​CSS Selectors

Where It Fits

Minimal Render

Sub-Components

Root

CategoryTabs

SearchBar

EmojiGrid

EmptyState

Actions and Events

Callback Props

onEmojiClick

onClose

Custom View Slots

Custom emoji data

Common Patterns

Lazy-loaded emoji picker

Compound composition

Keyboard Navigation

CSS Architecture

Key Selectors

Example: Brand-themed emoji keyboard

Customization Matrix

Props

CometChatEmojiKeyboard.Root

emojiData

onEmojiClick

onClose

className

children

CometChatEmojiKeyboard.CategoryTabs

className

CometChatEmojiKeyboard.SearchBar

placeholder

className

CometChatEmojiKeyboard.EmojiGrid

emojis

className

CometChatEmojiKeyboard.CategorySection

category

className

CometChatEmojiKeyboard.EmptyState

children

className

CSS Selectors