### Run Tutorial Example App

Source: https://github.com/getstream/stream-chat-react/blob/master/AGENTS.md

Starts the tutorial example application. Useful for testing features in a specific example context.

```bash
yarn start:tutorial
```

--------------------------------

### Run Vite Example App

Source: https://github.com/getstream/stream-chat-react/blob/master/AGENTS.md

Starts the Vite example application. Useful for testing features in a different example context.

```bash
yarn start:vite
```

--------------------------------

### Build All Example Apps

Source: https://github.com/getstream/stream-chat-react/blob/master/AGENTS.md

Builds all example applications within the monorepo. This ensures that all examples are compilable and functional.

```bash
yarn examples:build
```

--------------------------------

### Run Tutorial Browser

Source: https://github.com/getstream/stream-chat-react/blob/master/examples/tutorial/README.md

Starts the tutorial browser application for interactive exploration of chat tutorial steps.

```shell
yarn dev
```

--------------------------------

### Initialize Worktree Environment

Source: https://github.com/getstream/stream-chat-react/blob/master/src/components/ChannelHeader/plan.md

Commands to navigate to the project worktree and install dependencies.

```bash
cd ../stream-chat-react-worktrees/channel-header-figma
yarn install
```

--------------------------------

### Install Dependencies

Source: https://github.com/getstream/stream-chat-react/blob/master/examples/tutorial/README.md

Installs project dependencies using Yarn, leveraging workspaces to manage local SDK consumption.

```shell
yarn install
```

--------------------------------

### Install Stream Chat Dependencies

Source: https://github.com/getstream/stream-chat-react/blob/master/AI.md

Install the required stream-chat and stream-chat-react packages using npm or yarn.

```bash
npm install stream-chat stream-chat-react
# or
yarn add stream-chat stream-chat-react
```

--------------------------------

### Import CSS for Theming

Source: https://github.com/getstream/stream-chat-react/blob/master/ai-docs/docs-plan.md

Import CSS for theming. Use the root `dist/css/index.css` for general styling or `dist/css/*` for layout-only examples.

```css
import "dist/css/index.css";
```

```css
import "dist/css/*";
```

--------------------------------

### Initialize Minimal Chat Client

Source: https://github.com/getstream/stream-chat-react/blob/master/AI.md

A minimal example showing how to initialize the Stream Chat client and wrap the application with the Chat provider.

```tsx
import { Chat, useCreateChatClient } from 'stream-chat-react';
import 'stream-chat-react/dist/css/v2/index.css';

// Get your API key from: https://dashboard.getstream.io/
// For development, generate a token at: https://getstream.io/chat/docs/php/tokens_and_authentication/#manually-generating-tokens
const apiKey = 'YOUR_API_KEY';
const userId = 'YOUR_USER_ID';
const userName = 'YOUR_USER_NAME';
const userToken = 'YOUR_USER_TOKEN';

const App = () => {
  const client = useCreateChatClient({
    apiKey,
    tokenOrProvider: userToken,
    userData: { id: userId, name: userName },
  });

  if (!client) return <div>Setting up client & connection...</div>;

  return <Chat client={client}>Chat with client is ready!</Chat>;
};
```

--------------------------------

### Mock Builder Pattern Setup

Source: https://github.com/getstream/stream-chat-react/blob/master/CLAUDE.md

Standard test setup using the mock builder pattern for Stream Chat React. This includes initializing a test client, mocking APIs, and setting up a channel.

```typescript
// Standard test setup
const chatClient = await getTestClientWithUser({ id: 'test-user' });
useMockedApis(chatClient, [getOrCreateChannelApi(mockedChannelData)]);
const channel = chatClient.channel('messaging', channelId);
await channel.watch();
```

--------------------------------

### Conventional Commits Example

Source: https://github.com/getstream/stream-chat-react/blob/master/CLAUDE.md

Example of a commit message following the Conventional Commits specification. This format helps automate release management and provides clear commit history.

```plaintext
feat(MessageInput): add audio recording support

Implement MediaRecorder API integration with MP3 encoding.

Closes #123
```

--------------------------------

### Minimal Custom Gallery UI

Source: https://github.com/getstream/stream-chat-react/blob/master/src/components/Gallery/goal.md

Implement a minimal custom UI for the gallery using `useGalleryContext` to access navigation functions and the current item. This example demonstrates basic previous/next navigation and image display.

```tsx
import { Gallery, useGalleryContext, BaseImage } from 'stream-chat-react';

const MinimalGalleryUI = () => {
  const { currentItem, goToNext, goToPrevious } = useGalleryContext();

  return (
    <div className='minimal-gallery'>
      <button onClick={goToPrevious}>←</button>
      <BaseImage src={currentItem.image_url} alt={currentItem.fallback} />
      <button onClick={goToNext}>→</button>
    </div>
  );
};

<Gallery items={attachments} GalleryUI={MinimalGalleryUI} />;
```

--------------------------------

### Memoization Dependency Array Example

Source: https://github.com/getstream/stream-chat-react/blob/master/CLAUDE.md

Illustrates correct usage of dependency arrays in `useMemo` to prevent infinite re-renders. Avoid including unstable values like `channel.state.messages` or `channel.initialized`.

```typescript
useMemo(
  () => ({
    /* value */
  }),
  [
    channel.cid, // ✅ Stable - include this
    deleteMessage, // ✅ Stable callback
    // ❌ NOT channel.state.messages - causes infinite re-renders
    // ❌ NOT channel.initialized - changes constantly
  ],
);
```

--------------------------------

### Channel Header with displayMembers

Source: https://github.com/getstream/stream-chat-react/blob/master/ai-docs/docs-plan.md

Configure the custom header example to rely on `displayMembers` for member overflow.

```javascript
// Example configuration for ChannelHeader
<ChannelHeader displayMembers={true} />
```

--------------------------------

### Update Message Date Separator

Source: https://github.com/getstream/stream-chat-react/blob/master/ai-docs/docs-plan.md

This example shows how to handle the current default separator behavior and guidance for custom separators.

```javascript
// Example usage for custom-separator guidance
// (Actual implementation depends on specific needs)
```

--------------------------------

### Migrate Channel UI Overrides to WithComponents

Source: https://github.com/getstream/stream-chat-react/blob/master/ai-docs/ai-migration.md

Before: Channel component accepted UI override props directly. After: UI overrides are moved to the WithComponents wrapper. This example shows how to migrate custom input, message, message options, and modal components.

```tsx
// before
<Channel Input={CustomInput} Message={CustomMessage} MessageOptions={CustomActions} Modal={CustomModal}>
```

```tsx
// after
<WithComponents overrides={{
  MessageComposerUI: CustomInput,
  Message: CustomMessage,
  MessageActions: CustomActions,
  Modal: CustomModal,
}}>
  <Channel>...</Channel>
</WithComponents>
```

--------------------------------

### Add QuickDropdownToggleActionSetItem for Message Actions

Source: https://github.com/getstream/stream-chat-react/blob/master/ai-docs/breaking-changes.md

When customizing message actions, ensure a `quick-dropdown-toggle` item is included if you want dropdown actions to be reachable. Start from `defaultMessageActionSet` for easier customization.

```typescript
QuickDropdownToggleActionSetItem,
  MessageActionSetItem,
  MessageActionSet,
} from './types';

export const defaultMessageActionSet: MessageActionSet = [
  {
    type: 'separator',
  },
  {
    type: 'dropdown',
    actions: defaultMessageActions,
  },
  {
    type: 'quick-dropdown-toggle',
    actions: defaultMessageActions,
  },
];
```

--------------------------------

### Build Tutorial Browser

Source: https://github.com/getstream/stream-chat-react/blob/master/examples/tutorial/README.md

Builds the tutorial browser application for deployment.

```shell
yarn build
```

--------------------------------

### Build System Overview

Source: https://github.com/getstream/stream-chat-react/blob/master/CLAUDE.md

The build process involves four parallel tasks: translation extraction, Vite bundling, TypeScript declaration generation, and SCSS compilation. All outputs are directed to separate directories under 'dist/'.

```bash
yarn build

# Runs 4 tasks in parallel via concurrently:
# 1. yarn build-translations — Extracts t() calls via i18next-cli
# 2. vite build — Bundles 3 entry points (index, emojis, mp3-encoder) as ESM + CJS
# 3. tsc --project tsconfig.lib.json — Generates .d.ts type declarations to dist/types/
# 4. yarn build-styling — Compiles SCSS to dist/css/index.css
```

--------------------------------

### Import Gallery Styles in Index

Source: https://github.com/getstream/stream-chat-react/blob/master/src/components/Gallery/plan.md

SCSS file to aggregate gallery-related styles.

```scss
@use 'Gallery';
@use 'ModalGallery';
```

--------------------------------

### Development and Build Commands

Source: https://github.com/getstream/stream-chat-react/blob/master/CLAUDE.md

Essential commands for setting up, building, testing, and linting the Stream Chat React SDK project. Requires Node 24 and Yarn 4.

```bash
# Development (requires Node 24 — see .nvmrc)
# Yarn 4 is committed to .yarn/releases/ and activated via .yarnrc.yml
# (yarnPath). Any globally installed `yarn` shim launches it; no Corepack.
yarn install              # Setup (installs root + examples/* workspaces)
yarn build                # Full build (translations, Vite, types, SCSS)
yarn test                 # Run Jest tests
yarn test <pattern>       # Run specific test (e.g., yarn test Channel)
yarn lint-fix             # Fix all lint/format issues (prettier + eslint)
yarn types                # TypeScript type checking (noEmit mode)

# Examples (workspaces under examples/*)
yarn start:tutorial       # Start the tutorial example dev server
yarn start:vite           # Start the vite example dev server
yarn examples:build       # Build all examples

# E2E
yarn e2e-fixtures         # Generate e2e test fixtures
yarn e2e                  # Run Playwright tests

# Before committing
yarn lint-fix             # ALWAYS run this first
```

--------------------------------

### Integrate Gallery Styles into Main Index

Source: https://github.com/getstream/stream-chat-react/blob/master/src/components/Gallery/plan.md

Importing the gallery styling module into the main project stylesheet.

```scss
@use '../components/Gallery/styling' as Gallery;
```

--------------------------------

### Import Gallery Styles

Source: https://github.com/getstream/stream-chat-react/blob/master/src/components/Gallery/goal.md

Include the Gallery component styles within the main project stylesheet.

```scss
// In src/styling/index.scss
@use '../components/Gallery/styling' as Gallery;
```

--------------------------------

### Gallery Component Composition

Source: https://github.com/getstream/stream-chat-react/blob/master/src/components/Gallery/goal.md

Demonstrates the internal structure where Gallery provides context and GalleryUI consumes it.

```tsx
{
  /* Gallery provides context, GalleryUI consumes it */
}
<Gallery items={items} initialIndex={0}>
  {/* Default internal structure rendered by GalleryUI */}
  <div className='str-chat__gallery'>
    <div className='str-chat__gallery__main'>
      <button className='str-chat__gallery__nav-button--prev' />
      <BaseImage /> {/* or video player */}
      <button className='str-chat__gallery__nav-button--next' />
    </div>
    <div className='str-chat__gallery__position-indicator'>3 / 10</div>
  </div>
</Gallery>;
```

--------------------------------

### Layout Styling

Source: https://github.com/getstream/stream-chat-react/blob/master/AI.md

Apply basic CSS to ensure proper component positioning and sizing for the chat layout.

```css
html,
body,
#root {
  height: 100%;
}
body {
  margin: 0;
}
#root {
  display: flex;
}

.str-chat__channel-list {
  width: 30%;
}
.str-chat__channel {
  width: 100%;
}
.str-chat__thread {
  width: 45%;
}
```

--------------------------------

### Updated reactionOptions Support

Source: https://github.com/getstream/stream-chat-react/blob/master/ai-docs/breaking-changes.md

The `reactionOptions` configuration now supports a new `quick` / `extended` shape in addition to legacy arrays. This allows for more flexible customization of reaction options.

```typescript
src/components/Reactions/reactionOptions.tsx:18 now supports the new `quick` / `extended` reaction-options shape in addition to legacy arrays
```

--------------------------------

### Run Unit Tests with Yarn

Source: https://github.com/getstream/stream-chat-react/blob/master/AGENTS.md

Executes all unit and integration tests using Vitest. Ensure all tests pass before submitting changes.

```bash
yarn test
```

--------------------------------

### Implement Full Chat UI

Source: https://github.com/getstream/stream-chat-react/blob/master/AI.md

A complete implementation of the chat interface including channel lists, message windows, and threads.

```tsx
import type { ChannelFilters, ChannelOptions, ChannelSort, User } from 'stream-chat';
import {
  Chat,
  Channel,
  ChannelHeader,
  ChannelList,
  MessageInput,
  MessageList,
  Thread,
  Window,
  useCreateChatClient,
} from 'stream-chat-react';
import 'stream-chat-react/dist/css/v2/index.css';

// Get your API key from: https://dashboard.getstream.io/
// For development, generate a token at: https://getstream.io/chat/docs/php/tokens_and_authentication/#manually-generating-tokens
const apiKey = 'YOUR_API_KEY';
const userId = 'YOUR_USER_ID';
const userName = 'YOUR_USER_NAME';
const userToken = 'YOUR_USER_TOKEN';

const user: User = {
  id: userId,
  name: userName,
  image: `https://getstream.io/random_png/?name=${userName}`,
};

const sort: ChannelSort = { last_message_at: -1 };
const filters: ChannelFilters = {
  type: 'messaging',
  members: { $in: [userId] },
};
const options: ChannelOptions = {
  limit: 10,
};

const App = () => {
  const client = useCreateChatClient({
    apiKey,
    tokenOrProvider: userToken,
    userData: user,
  });

  if (!client) return <div>Setting up client & connection...</div>;

  return (
    <Chat client={client}>
      <ChannelList filters={filters} sort={sort} options={options} />
      <Channel>
        <Window>
          <ChannelHeader />
          <MessageList />
          <MessageInput />
        </Window>
        <Thread />
      </Channel>
    </Chat>
  );
};
```

--------------------------------

### Expose ChannelListUI via ComponentContext

Source: https://github.com/getstream/stream-chat-react/blob/master/ai-docs/breaking-changes.md

The `ChannelListUI`, `ChannelListItemActionButtons`, and `ChannelListItemUI` components are now exposed through the `ComponentContext`. This is the new way to customize the channel list UI.

```typescript
src/context/ComponentContext.tsx:106 through :111 expose ChannelListUI, ChannelListItemActionButtons, and ChannelListItemUI
```

--------------------------------

### Lint Project with Yarn

Source: https://github.com/getstream/stream-chat-react/blob/master/AGENTS.md

Runs the linter across the entire project to check for code style and potential errors. This should be run before committing.

```bash
yarn lint
```

--------------------------------

### JSX for Conditional Rendering (Rejected Approach)

Source: https://github.com/getstream/stream-chat-react/blob/master/src/components/Gallery/decisions.md

Illustrates the previous approach of conditionally rendering navigation buttons based on state. This method was rejected due to layout instability and accessibility concerns.

```jsx
{hasPrevious && <NavButton />}
{hasNext && <NavButton />}
```

--------------------------------

### Split File Handling Across New Containers

Source: https://github.com/getstream/stream-chat-react/blob/master/ai-docs/breaking-changes.md

File handling has been split into specialized containers. Use OtherFilesContainer, AudioContainer, VoiceRecordingContainer, or VideoContainer as needed for different file types.

```typescript
FileContainer
OtherFilesContainer
VideoContainer
```

--------------------------------

### Migrate Channel Search to WithComponents

Source: https://github.com/getstream/stream-chat-react/blob/master/ai-docs/ai-migration.md

The `ChannelList` component no longer accepts `additionalChannelSearchProps` or `ChannelSearch`. Customize search behavior by providing a custom `Search` component via `WithComponents`.

```tsx
// before
<ChannelList
  additionalChannelSearchProps={{ placeholder: 'Search...' }}
  ChannelSearch={ChannelSearch}
  showChannelSearch
/>;

// after
const CustomSearch = () => <Search placeholder='Search...' exitSearchOnInputBlur />;

<WithComponents overrides={{ Search: CustomSearch }}>
  <ChannelList showChannelSearch />
</WithComponents>
```

--------------------------------

### Configure Link Preview Display Count

Source: https://github.com/getstream/stream-chat-react/blob/master/ai-docs/ai-migration.md

The default display count for link previews has changed from showing all to displaying only one. Adjust the displayLinkCount prop on LinkPreviewList to show more previews.

```tsx
<LinkPreviewList displayLinkCount={5} />
```

--------------------------------

### Emoji Picker Integration

Source: https://github.com/getstream/stream-chat-react/blob/master/AI.md

Initialize emoji data and pass the picker component and search index to the Channel component.

```tsx
import { EmojiPicker } from 'stream-chat-react/emojis';
import { init, SearchIndex } from 'emoji-mart';
import data from '@emoji-mart/data';

init({ data });

<Channel EmojiPicker={EmojiPicker} emojiSearchIndex={SearchIndex}>
  {/* ... */}
</Channel>;
```

--------------------------------

### GalleryUI Component Structure

Source: https://github.com/getstream/stream-chat-react/blob/master/src/components/Gallery/plan.md

Outlines the DOM structure for the GalleryUI component using specific CSS classes.

```text
.str-chat__gallery
  .str-chat__gallery__main
    .str-chat__gallery__nav-button--prev (button)
    .str-chat__gallery__media
      BaseImage (for images) or video element (for videos)
    .str-chat__gallery__nav-button--next (button)
  .str-chat__gallery__position-indicator
```

--------------------------------

### ModalGallery Component Props

Source: https://github.com/getstream/stream-chat-react/blob/master/src/components/Gallery/goal.md

Configuration for the ModalGallery component, which renders a thumbnail grid and handles modal display logic.

```APIDOC
## ModalGallery Component Props

### Description
Displays a grid of thumbnails that opens a full-screen Gallery carousel in a modal when clicked.

### Parameters
#### Request Body
- **items** (GalleryItem[]) - Required - Array of media attachments to display in the grid and subsequent modal.
```

--------------------------------

### Old API: ChannelList Preview Prop

Source: https://github.com/getstream/stream-chat-react/blob/master/ai-docs/breaking-changes.md

In v13.14.2, the `ChannelList` component exposed a `Preview` prop for customizing channel previews. This prop has been removed.

```typescript
v13.14.2:src/components/ChannelList/ChannelList.tsx:144 through :145 exposed Preview?: React.ComponentType<ChannelPreviewUIComponentProps>
```

--------------------------------

### Add QuickDropdownToggle for Channel List Item Actions

Source: https://github.com/getstream/stream-chat-react/blob/master/ai-docs/breaking-changes.md

When customizing channel actions, explicitly preserve or replace the default `quick-dropdown-toggle` item. The SDK no longer injects the toggle button automatically.

```typescript
QuickDropdownToggleActionSetItem,
  ChannelActionSetItem,
  ChannelActionSet,
} from './types';

export const defaultChannelActionSet: ChannelActionSet = [
  {
    type: 'separator',
  },
  {
    type: 'dropdown',
    actions: defaultChannelActions,
  },
  {
    type: 'quick-dropdown-toggle',
    actions: defaultChannelActions,
  },
];
```

--------------------------------

### Shell Branch Architecture Diagram

Source: https://github.com/getstream/stream-chat-react/blob/master/developers/BRANCHES.md

Illustrates the branching strategy where feature branches stem from the master branch and are eventually merged back.

```shell
NPM <--- master <--- branch_solution_x
                <--- branch_solution_y
                <--- branch_solution_x
                ...
```

--------------------------------

### Gallery in Modal (Manual Composition)

Source: https://github.com/getstream/stream-chat-react/blob/master/src/components/Gallery/goal.md

Manually compose the `Gallery` component within a `Modal` for custom control over modal behavior. This approach requires managing the modal's open state and the selected index.

```tsx
import { Gallery, Modal } from 'stream-chat-react';

const MyComponent = () => {
  const [isOpen, setIsOpen] = useState(false);
  const [selectedIndex, setSelectedIndex] = useState(0);
  const [attachments] = useState<(LocalImageAttachment | LocalVideoAttachment)[]>([]);

  const openGallery = (index: number) => {
    setSelectedIndex(index);
    setIsOpen(true);
  };

  return (
    <>
      <button onClick={() => openGallery(0)}>Open Gallery</button>
      <Modal
        open={isOpen}
        onClose={() => setIsOpen(false)}
        className='str-chat__gallery-modal'
      >
        <Gallery items={attachments} initialIndex={selectedIndex} />
      </Modal>
    </>
  );
};

```

--------------------------------

### Custom Gallery UI Component

Source: https://github.com/getstream/stream-chat-react/blob/master/src/components/Gallery/goal.md

Provide a custom `GalleryUI` component that consumes `GalleryContext` to control the gallery's appearance and behavior. Ensure all necessary context values are destructured and used appropriately.

```tsx
import { Gallery, useGalleryContext } from 'stream-chat-react';

const CustomGalleryUI = () => {
  const {
    currentItem,
    currentIndex,
    itemCount,
    goToNext,
    goToPrevious,
    hasNext,
    hasPrevious,
  } = useGalleryContext();

  return (
    <div className='my-custom-gallery'>
      {hasPrevious && <button onClick={goToPrevious}>Prev</button>}
      <img src={currentItem.image_url} />
      {hasNext && <button onClick={goToNext}>Next</button>}
      <span>
        {currentIndex + 1} / {itemCount}
      </span>
    </div>
  );
};

// Usage
<Gallery items={attachments} GalleryUI={CustomGalleryUI} />;
```

--------------------------------

### Adding Custom Components

Source: https://github.com/getstream/stream-chat-react/blob/master/CLAUDE.md

Custom components can be added to ComponentContext and provided as default implementations. They can be overridden via props on components like <Channel>.

```javascript
1. Add to ComponentContext (src/context/ComponentContext.tsx)
2. Provide default implementation
3. Allow override via prop: <Channel Message={CustomMessage} />
4. Access via useComponentContext()
```

--------------------------------

### Migrate Media Flows to MediaContainer

Source: https://github.com/getstream/stream-chat-react/blob/master/ai-docs/breaking-changes.md

When using low-level containers directly, migrate media flows to the new MediaContainer, passing attachments as an array. This replaces older methods for handling various media types.

```typescript
MediaContainer({ attachments })

```

--------------------------------

### Register Custom Attachment Renderer

Source: https://github.com/getstream/stream-chat-react/blob/master/ai-docs/docs-plan.md

Register a custom attachment renderer using `WithComponents`. This is useful for custom attachment types like payment attachments.

```javascript
import { WithComponents } from '@stream-chat/react-native-core';

// ...

<WithComponents
  components={{
    Attachment
  }}
  // ...
/>
```

--------------------------------

### Gallery Component Props

Source: https://github.com/getstream/stream-chat-react/blob/master/src/components/Gallery/goal.md

Configuration options for the Gallery component, which manages media state and carousel navigation.

```APIDOC
## Gallery Component Props

### Description
The Gallery component renders media items in a carousel format and manages navigation state.

### Parameters
#### Request Body
- **items** (GalleryItem[]) - Required - Array of media attachments (LocalVideoAttachment or LocalImageAttachment) to display.
- **initialIndex** (number) - Optional - The starting index of the item to display (default: 0).
- **onIndexChange** (function) - Optional - Callback triggered when the active item index changes.
- **GalleryUI** (React.ComponentType) - Optional - Custom UI component to replace the default carousel interface.
```

--------------------------------

### Composer-Driven Message Editing

Source: https://github.com/getstream/stream-chat-react/blob/master/ai-docs/ai-migration.md

Initialize the message composer with existing message content for editing and clear it to cancel.

```tsx
// customize preview via EditedMessagePreview in WithComponents
import { useMessageComposerController, useMessageContext } from 'stream-chat-react';

const { message } = useMessageContext();
const messageComposer = useMessageComposerController();

messageComposer.initState({ composition: message }); // start
messageComposer.clear(); // cancel
```

--------------------------------

### Using StateStore for Reactive State

Source: https://github.com/getstream/stream-chat-react/blob/master/CLAUDE.md

The useStateStore hook from './store' can be used to access reactive SDK state, such as the channels array.

```typescript
import { useStateStore } from './store';
const channels = useStateStore(chatClient.state.channelsArray);
```

--------------------------------

### Commit Message Header Format

Source: https://github.com/getstream/stream-chat-react/blob/master/developers/COMMIT.md

The standard structure for the first line of a commit message.

```shell
<type>(<scope>): <short summary>
```

--------------------------------

### GalleryContext API

Source: https://github.com/getstream/stream-chat-react/blob/master/src/components/Gallery/goal.md

The context API exposed by the Gallery component, accessible via the useGalleryContext hook.

```APIDOC
## GalleryContext API

### Description
Provides state and navigation methods for the Gallery component.

### Response
- **items** (GalleryItem[]) - All items in the gallery.
- **currentIndex** (number) - Currently displayed item index.
- **currentItem** (GalleryItem) - Currently displayed item.
- **itemCount** (number) - Total number of items.
- **goToIndex** (function) - Navigate to a specific index.
- **goToNext** (function) - Navigate to the next item.
- **goToPrevious** (function) - Navigate to the previous item.
- **hasNext** (boolean) - Whether there is a next item.
- **hasPrevious** (boolean) - Whether there is a previous item.
```

--------------------------------

### Fix Lint Issues with Yarn

Source: https://github.com/getstream/stream-chat-react/blob/master/AGENTS.md

Run this command to automatically fix linting issues in the project. Ensure this is done before committing.

```bash
yarn lint-fix
```

--------------------------------

### Chat Component with Sidebar State

Source: https://github.com/getstream/stream-chat-react/blob/master/ai-docs/docs-plan.md

Reflects the current sidebar-state behavior and the `str-chat__channel-list` root class.

```javascript
import { Chat } from 'stream-chat-react';

// ...

<Chat
  // ...
  // Current sidebar-state behavior is reflected here
>
  {/* ... */}
</Chat>
```

--------------------------------

### Set Custom Query Limits for Channel and ChannelList

Source: https://github.com/getstream/stream-chat-react/blob/master/ai-docs/ai-migration.md

Default query limits are no longer injected by `Channel` and `ChannelList`. Specify query limits using `channelQueryOptions` for `Channel` and `options` for `ChannelList`.

```tsx
<Channel channelQueryOptions={{ messages: { limit: 20 } }}>...</Channel>
<ChannelList options={{ limit: 30 }} />
```

--------------------------------

### Customizing Message UI with WithComponents

Source: https://github.com/getstream/stream-chat-react/blob/master/README.md

Swap out the default Message UI component with a custom one using the WithComponents override. This allows for UI changes without altering the underlying message logic.

```jsx
<Channel>
  <Window>
    <ChannelHeader />
    <WithComponents overrides={{ MessageUI: CustomMessageUI }}>
      <MessageList />
    </WithComponents>
    <MessageComposer />
  </Window>
  <Thread />
</Channel>
```

--------------------------------

### ChannelHeader Rendering HeaderStartContent (v14)

Source: https://github.com/getstream/stream-chat-react/blob/master/ai-docs/breaking-changes.md

In v14, ChannelHeader renders HeaderStartContent from ComponentContext, replacing the previous built-in sidebar toggle. This allows for custom UI injection for sidebar controls.

```typescript
const ChannelHeader = ({
  // ... other props
}: ChannelHeaderProps) => {
  // ...
  return (
    <header className={headerClassNames}>
      <ComponentContext
        value={{
          // ... other context values
          HeaderStartContent,
          HeaderEndContent,
        }}
      >
        {/* ... */}
      </ComponentContext>
    </header>
  );
};
```

--------------------------------

### Import Emoji Picker Stylesheet

Source: https://github.com/getstream/stream-chat-react/blob/master/ai-docs/ai-migration.md

If the application uses EmojiPicker, import its dedicated stylesheet. This ensures that the emoji picker component is styled correctly.

```typescript
import 'stream-chat-react/css/emoji-picker.css';
```

--------------------------------

### Use New Cooldown Hooks and Component

Source: https://github.com/getstream/stream-chat-react/blob/master/ai-docs/ai-migration.md

MessageComposerContext no longer exposes cooldown-related state. Use the new useCooldownRemaining, useIsCooldownActive hooks, and the CooldownTimer component for managing cooldowns.

```tsx
import {
  useCooldownRemaining,
  useIsCooldownActive,
  CooldownTimer,
} from 'stream-chat-react';

const cooldownRemaining = useCooldownRemaining();
const isCooldownActive = useIsCooldownActive();

<CooldownTimer />; // zero-prop
```

--------------------------------

### Compose Gallery in a Modal

Source: https://github.com/getstream/stream-chat-react/blob/master/src/components/Gallery/goal.md

Wrap the Gallery component with the Modal component to enable custom modal behavior.

```tsx
<Modal open={isOpen} onClose={handleClose} className='str-chat__gallery-modal'>
  <Gallery items={attachments} initialIndex={selectedIndex} />
</Modal>
```

--------------------------------

### Update reaction_counts and reactionOptions

Source: https://github.com/getstream/stream-chat-react/blob/master/ai-docs/breaking-changes.md

Replace `reaction_counts` with `reaction_groups`. Move `reactionOptions` configuration to `<WithComponents overrides={{ reactionOptions }}>` instead of passing it directly to `MessageReactions`.

```typescript
src/components/Reactions/hooks/useProcessReactions.tsx:10
through :13
now accept only `own_reactions`, `reaction_groups`, `reactions`, and `sortReactions`
```

--------------------------------

### Theming CSS Variable Hierarchy

Source: https://github.com/getstream/stream-chat-react/blob/master/CLAUDE.md

Theming utilizes a three-tier CSS variable hierarchy: primitives sourced from Figma, semantic tokens with light/dark variants, and component-specific tokens.

```css
1. Primitives (src/styling/variables.css) — Figma-sourced color palette tokens
2. Semantic tokens (src/styling/_global-theme-variables.scss) — Light/dark mode mappings (e.g., --str-chat__primary-color)
3. Component tokens (per-component SCSS) — e.g., --str-chat__message-bubble-background-color
```