Change Scope - CometChat Docs

AI Integration Quick Reference

{
  "component": "CometChatChangeScope",
  "package": "@cometchat/chat-uikit-react",
  "import": "import { CometChatChangeScope } from \"@cometchat/chat-uikit-react\";",
  "cssImport": "import \"@cometchat/chat-uikit-react/css-variables.css\";",
  "description": "A dialog component for changing a group member's scope with radio selection, async confirmation, and built-in loading/error states.",
  "cssRootClass": ".cometchat-change-scope",
  "subComponents": ["Root", "Header", "ScopeList", "ScopeOption", "Actions", "ErrorMessage"],
  "props": {
    "Root": {
      "options": { "type": "CometChatChangeScopeOptionData[]", "default": "undefined", "note": "Required." },
      "defaultSelection": { "type": "string", "default": "''" },
      "onScopeChanged": { "type": "(scopeId: string) => Promise<void>", "default": "undefined" },
      "onClose": { "type": "() => void", "default": "undefined" },
      "className": { "type": "string", "default": "undefined" },
      "children": { "type": "ReactNode", "default": "undefined" }
    },
    "Header": {
      "title": { "type": "string", "default": "Localized 'Change Scope'" },
      "description": { "type": "string", "default": "Localized subtitle" },
      "showIcon": { "type": "boolean", "default": "true" },
      "className": { "type": "string", "default": "undefined" }
    },
    "ScopeList": {
      "className": { "type": "string", "default": "undefined" },
      "children": { "type": "ReactNode", "default": "undefined" }
    },
    "ScopeOption": {
      "option": { "type": "CometChatChangeScopeOptionData", "default": "undefined", "note": "Required." },
      "className": { "type": "string", "default": "undefined" }
    },
    "Actions": {
      "submitText": { "type": "string", "default": "Localized 'Save'" },
      "cancelText": { "type": "string", "default": "Localized 'Cancel'" },
      "className": { "type": "string", "default": "undefined" }
    },
    "ErrorMessage": {
      "className": { "type": "string", "default": "undefined" }
    }
  },
  "types": {
    "CometChatChangeScopeOptionData": {
      "id": "string",
      "label": "string"
    },
    "CometChatChangeScopeContextValue": {
      "options": "CometChatChangeScopeOptionData[]",
      "selectedId": "string",
      "defaultSelection": "string",
      "isLoading": "boolean",
      "error": "string | null",
      "selectOption": "(id: string) => void",
      "confirmChange": "() => void",
      "cancel": "() => void",
      "hasChanged": "boolean"
    }
  }
}

Where It Fits

CometChatChangeScope is a base component used by CometChatGroupMembers when a group owner or admin needs to change another member’s role. It renders a self-contained dialog with a radio group, confirm/cancel buttons, and automatic loading/error handling driven by the onScopeChanged promise.

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

const scopeOptions = [
  { id: "admin", label: "Admin" },
  { id: "moderator", label: "Moderator" },
  { id: "participant", label: "Participant" },
];

function GroupMemberScopeDialog({ currentScope, onScopeChanged, onClose }) {
  return (
    <CometChatChangeScope.Root
      options={scopeOptions}
      defaultSelection={currentScope}
      onScopeChanged={onScopeChanged}
      onClose={onClose}
    >
      <CometChatChangeScope.Header />
      <CometChatChangeScope.ScopeList>
        {scopeOptions.map((opt) => (
          <CometChatChangeScope.ScopeOption key={opt.id} option={opt} />
        ))}
      </CometChatChangeScope.ScopeList>
      <CometChatChangeScope.ErrorMessage />
      <CometChatChangeScope.Actions />
    </CometChatChangeScope.Root>
  );
}

Minimal Render

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

const options = [
  { id: "admin", label: "Admin" },
  { id: "moderator", label: "Moderator" },
  { id: "participant", label: "Participant" },
];

function Demo() {
  return (
    <CometChatChangeScope.Root options={options} defaultSelection="participant">
      <CometChatChangeScope.Header />
      <CometChatChangeScope.ScopeList>
        {options.map((opt) => (
          <CometChatChangeScope.ScopeOption key={opt.id} option={opt} />
        ))}
      </CometChatChangeScope.ScopeList>
      <CometChatChangeScope.Actions />
    </CometChatChangeScope.Root>
  );
}

Root CSS class: .cometchat-change-scope

Sub-Components

CometChatChangeScope is a compound component with six sub-components:

Sub-component	Purpose
`Root`	Dialog container. Provides context, focus trap, keyboard handling, and state management.
`Header`	Icon, title, and description text.
`ScopeList`	Radio group container with `role="radiogroup"`.
`ScopeOption`	A single radio option representing a scope level.
`Actions`	Cancel and submit buttons. Submit is disabled until the selection changes.
`ErrorMessage`	Displays an error message (with `role="alert"`) when scope change fails.

Root

The outermost wrapper. Initializes the useCometChatChangeScope hook, provides context to all children, traps focus within the dialog, and handles Escape to close.

<CometChatChangeScope.Root
  options={scopeOptions}
  defaultSelection="participant"
  onScopeChanged={async (scopeId) => {
    await CometChat.updateGroupMemberScope(groupId, memberId, scopeId);
  }}
  onClose={() => setShowDialog(false)}
>
  {/* Header, ScopeList, ErrorMessage, Actions */}
</CometChatChangeScope.Root>

Renders a scope icon, title, and description. All text defaults to localized strings but can be overridden via props. Set showIcon={false} to hide the icon.

<CometChatChangeScope.Header
  title="Update Role"
  description="Select a new role for this member."
  showIcon={false}
/>

ScopeList

A container with role="radiogroup". Wrap ScopeOption children inside it.

<CometChatChangeScope.ScopeList>
  {options.map((opt) => (
    <CometChatChangeScope.ScopeOption key={opt.id} option={opt} />
  ))}
</CometChatChangeScope.ScopeList>

ScopeOption

A single radio input with a label. Reads context to determine if it is the currently selected option.

<CometChatChangeScope.ScopeOption
  option={{ id: "admin", label: "Admin" }}
/>

Actions

Cancel and submit buttons. The submit button is automatically disabled when the selection matches defaultSelection or while loading. Shows a spinner during the async onScopeChanged call.

<CometChatChangeScope.Actions submitText="Update" cancelText="Dismiss" />

ErrorMessage

Renders only when the onScopeChanged promise rejects. Uses role="alert" so screen readers announce the error immediately.

<CometChatChangeScope.ErrorMessage />

Common Patterns

Async scope change with SDK

import { CometChatChangeScope } from "@cometchat/chat-uikit-react";
import "@cometchat/chat-uikit-react/css-variables.css";
import { CometChat } from "@cometchat/chat-sdk-javascript";

const scopeOptions = [
  { id: "admin", label: "Admin" },
  { id: "moderator", label: "Moderator" },
  { id: "participant", label: "Participant" },
];

function ChangeScopeDialog({ groupGuid, memberUid, currentScope, onClose }) {
  const handleScopeChanged = async (scopeId: string) => {
    await CometChat.updateGroupMemberScope(groupGuid, memberUid, scopeId);
  };

  return (
    <CometChatChangeScope.Root
      options={scopeOptions}
      defaultSelection={currentScope}
      onScopeChanged={handleScopeChanged}
      onClose={onClose}
    >
      <CometChatChangeScope.Header />
      <CometChatChangeScope.ScopeList>
        {scopeOptions.map((opt) => (
          <CometChatChangeScope.ScopeOption key={opt.id} option={opt} />
        ))}
      </CometChatChangeScope.ScopeList>
      <CometChatChangeScope.ErrorMessage />
      <CometChatChangeScope.Actions />
    </CometChatChangeScope.Root>
  );
}

Custom header without icon

<CometChatChangeScope.Root options={options} defaultSelection="participant">
  <CometChatChangeScope.Header
    title="Member Role"
    description="Choose the appropriate role."
    showIcon={false}
  />
  <CometChatChangeScope.ScopeList>
    {options.map((opt) => (
      <CometChatChangeScope.ScopeOption key={opt.id} option={opt} />
    ))}
  </CometChatChangeScope.ScopeList>
  <CometChatChangeScope.Actions />
</CometChatChangeScope.Root>

Without error message display

Omit the ErrorMessage sub-component if you handle errors externally:

<CometChatChangeScope.Root
  options={options}
  defaultSelection="participant"
  onScopeChanged={handleChange}
  onClose={onClose}
>
  <CometChatChangeScope.Header />
  <CometChatChangeScope.ScopeList>
    {options.map((opt) => (
      <CometChatChangeScope.ScopeOption key={opt.id} option={opt} />
    ))}
  </CometChatChangeScope.ScopeList>
  <CometChatChangeScope.Actions />
</CometChatChangeScope.Root>

The change scope dialog is fully keyboard-accessible:

Key	Behavior
`Tab`	Moves focus to the next focusable element (trapped within the dialog)
`Shift+Tab`	Moves focus to the previous focusable element (wraps around)
`Escape`	Closes the dialog and returns focus to the trigger element
`Enter` / `Space`	Selects the focused radio option or activates a button

When the dialog mounts, focus automatically moves to the first focusable element. When it unmounts, focus returns to the element that had focus before the dialog opened.

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

Key Selectors

Target	Selector
Root container	`.cometchat-change-scope`
Header wrapper	`.cometchat-change-scope__header`
Icon container	`.cometchat-change-scope__icon-container`
Icon	`.cometchat-change-scope__icon`
Title	`.cometchat-change-scope__title`
Description	`.cometchat-change-scope__description`
Radio group list	`.cometchat-change-scope__list`
List item (option row)	`.cometchat-change-scope__list-item`
Option label text	`.cometchat-change-scope__list-item-label`
Radio input	`.cometchat-change-scope__radio`
Button container	`.cometchat-change-scope__button-container`
Cancel button wrapper	`.cometchat-change-scope__cancel-button`
Submit button wrapper	`.cometchat-change-scope__submit-button`
Error message	`.cometchat-change-scope__error-view`

Example: Brand-themed change scope dialog

App.css

.cometchat-change-scope {
  border-radius: 12px;
  border-color: var(--brand-border);
}

.cometchat-change-scope__icon-container {
  background: var(--brand-surface-light);
}

.cometchat-change-scope__list-item:hover {
  background: var(--brand-hover);
}

.cometchat-change-scope__error-view {
  background: var(--brand-error-bg);
  color: var(--brand-error-text);
}

Customization Matrix

What to change	Where	Property/API	Example
Scope options	Component props	`options` on `Root`	`<Root options={[...]}>`
Default selection	Component props	`defaultSelection` on `Root`	`<Root defaultSelection="admin">`
Handle scope change	Component props	`onScopeChanged` on `Root`	`<Root onScopeChanged={fn}>`
Header text	Component props	`title`, `description` on `Header`	`<Header title="Update Role">`
Hide icon	Component props	`showIcon` on `Header`	`<Header showIcon={false}>`
Button labels	Component props	`submitText`, `cancelText` on `Actions`	`<Actions submitText="Update">`
Hide error display	Composition	Omit `ErrorMessage` sub-component	Don’t render `<ErrorMessage />`
Change visual styling	Global CSS	`.cometchat-change-scope` selectors	See example above

Props

All props are optional unless noted otherwise.

CometChatChangeScope.Root

options

Array of scope options to display in the radio group.


Type	`CometChatChangeScopeOptionData[]`
Default	`undefined`

Required.

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

defaultSelection

The id of the initially selected scope option. The submit button stays disabled until the user selects a different option.


Type	`string`
Default	`''`

onScopeChanged

Called when the user clicks the submit button. Receives the selected scope id. Return a Promise — the component shows a loading spinner while it resolves and displays an error if it rejects.


Type	`(scopeId: string) => Promise<void>`
Default	`undefined`

onClose

Called when the user clicks cancel or presses Escape. Also called automatically after a successful onScopeChanged resolution.


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

className

Custom CSS class appended to the root container.


Type	`string`
Default	`undefined`

children

Content rendered inside the dialog. Typically Header, ScopeList, ErrorMessage, and Actions sub-components.


Type	`ReactNode`
Default	`undefined`

CometChatChangeScope.Header

title

Title text displayed in the header. Defaults to the localized “Change Scope” string.


Type	`string`
Default	Localized `"Change Scope"`

description

Description text below the title. Defaults to the localized subtitle.


Type	`string`
Default	Localized subtitle

showIcon

Whether to display the scope icon above the title.


Type	`boolean`
Default	`true`

className

Custom CSS class appended to the header container.


Type	`string`
Default	`undefined`

CometChatChangeScope.ScopeList

className

Custom CSS class appended to the radio group container.


Type	`string`
Default	`undefined`

children

The ScopeOption sub-components to render.


Type	`ReactNode`
Default	`undefined`

CometChatChangeScope.ScopeOption

option

The scope option data object.


Type	`CometChatChangeScopeOptionData`
Default	`undefined`

Required.

className

Custom CSS class appended to the option row.


Type	`string`
Default	`undefined`

CometChatChangeScope.Actions

submitText

Text for the submit button. Defaults to the localized “Save” string.


Type	`string`
Default	Localized `"Save"`

cancelText

Text for the cancel button. Defaults to the localized “Cancel” string.


Type	`string`
Default	Localized `"Cancel"`

className

Custom CSS class appended to the button container.


Type	`string`
Default	`undefined`

CometChatChangeScope.ErrorMessage

className

Custom CSS class appended to the error message container.


Type	`string`
Default	`undefined`

CSS Selectors

Target	Selector
Root	`.cometchat-change-scope`
Header	`.cometchat-change-scope__header`
Icon container	`.cometchat-change-scope__icon-container`
Icon	`.cometchat-change-scope__icon`
Title	`.cometchat-change-scope__title`
Description	`.cometchat-change-scope__description`
Radio group	`.cometchat-change-scope__list`
Option row	`.cometchat-change-scope__list-item`
Option label	`.cometchat-change-scope__list-item-label`
Radio input	`.cometchat-change-scope__radio`
Button container	`.cometchat-change-scope__button-container`
Cancel button	`.cometchat-change-scope__cancel-button`
Submit button	`.cometchat-change-scope__submit-button`
Error message	`.cometchat-change-scope__error-view`

Documentation Index

​Where It Fits

​Minimal Render

​Sub-Components

​Root

​Header

​ScopeList

​ScopeOption

​Actions

​ErrorMessage

​Common Patterns

​Async scope change with SDK

​Custom header without icon

​Without error message display

​Keyboard Navigation

​CSS Architecture

​Key Selectors

​Example: Brand-themed change scope dialog

​Customization Matrix

​Props

​CometChatChangeScope.Root

​options

​defaultSelection

​onScopeChanged

​onClose

​className

​children

​CometChatChangeScope.Header

​title

​description

​showIcon

​className

​CometChatChangeScope.ScopeList

​className

​children

​CometChatChangeScope.ScopeOption

​option

​className

​CometChatChangeScope.Actions

​submitText

​cancelText

​className

​CometChatChangeScope.ErrorMessage

​className

​CSS Selectors

Where It Fits

Minimal Render

Sub-Components

Root

Header

ScopeList

ScopeOption

Actions

ErrorMessage

Common Patterns

Async scope change with SDK

Custom header without icon

Without error message display

Keyboard Navigation

CSS Architecture

Key Selectors

Example: Brand-themed change scope dialog

Customization Matrix

Props

CometChatChangeScope.Root

options

defaultSelection

onScopeChanged

onClose

className

children

CometChatChangeScope.Header

title

description

showIcon

className

CometChatChangeScope.ScopeList

className

children

CometChatChangeScope.ScopeOption

option

className

CometChatChangeScope.Actions

submitText

cancelText

className

CometChatChangeScope.ErrorMessage

className

CSS Selectors