# Getting Started

> This section gives a high-level overview of setup, core components, and how they fit together. For a full step-by-step React app setup, see the [React Chat tutorial](https://getstream.io/chat/react-chat/tutorial/).

## Best Practices

- Follow the tutorial once end-to-end before diverging into custom layouts.
- Keep `Chat` and `Channel` as the top-level providers to ensure contexts flow correctly.
- Use `useCreateChatClient` for lifecycle management; avoid manual connect/disconnect logic.
- Start with default components and override selectively to minimize custom surface area.
- Define channel types and permissions early so UI behavior matches server rules.

## Your First App with Stream Chat React

Before starting, install `stream-chat-react` (and `stream-chat`) as described in [Installation](/chat/docs/sdk/react/v13/basics/installation/).

<admonition type="note">

You’ll also need to create a Stream Chat app and [generate a user token](/chat/docs/react/tokens_and_authentication/).

</Admonition>

The example below is the minimum code to render a working chat UI.

The [`Chat`](/chat/docs/sdk/react/v13/components/core-components/chat/) and [`Channel`](/chat/docs/sdk/react/v13/components/core-components/channel/) components are React context providers. They pass UI, state, and action handlers to their children.

```tsx
import {
  Chat,
  Channel,
  ChannelList,
  Window,
  ChannelHeader,
  MessageList,
  MessageInput,
  Thread,
  useCreateChatClient,
} from "stream-chat-react";
import "stream-chat-react/dist/css/v2/index.css";

const apiKey = "your-api-key";
const userId = "user-id";
const token = "authentication-token";

const filters = { members: { $in: [userId] }, type: "messaging" };
const options = { presence: true, state: true };
const sort = { last_message_at: -1 };

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

  if (!client) return <div>Loading...</div>;

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

To organize the components in a chat messenger layout, you can start with the following SCSS:

```scss
html,
body,
#root {
  margin: unset;
  padding: unset;
  height: 100%;
}

#root {
  display: flex;
  height: 100%;

  .str-chat__channel-list {
    position: fixed;
    z-index: 1;
    height: 100%;
    width: 0;
    flex-shrink: 0;
    box-shadow: 0 0 8px rgba(0, 0, 0, 0.15);

    &--open {
      width: 30%;
      position: fixed;
    }
    transition: width 0.3s ease-out;
  }

  .str-chat__channel {
    flex: 1;
    min-width: 0;
  }

  .str-chat__main-panel {
    min-width: 0;
    flex: 1;

    &--thread-open {
      display: none;
    }
  }

  .str-chat__thread {
    flex: 1;
    height: 100%;
    position: fixed;
    z-index: 1;
  }

  .str-chat__channel-header .str-chat__header-hamburger {
    width: 30px;
    height: 38px;
    padding: var(--xxs-p);
    margin-right: var(--xs-m);
    display: flex;
    align-items: center;
    justify-content: center;
    cursor: pointer;
    border: none;
    background: transparent;

    &:hover {
      svg path {
        fill: var(--primary-color);
      }
    }
  }

  @media screen and (min-width: 768px) {
    .str-chat__channel-list {
      width: 30%;
      position: initial;
      z-index: 0;
    }

    .str-chat__thread {
      position: initial;
      z-index: 0;
    }

    .str-chat__channel-header .str-chat__header-hamburger {
      display: none;
    }
  }

  @media screen and (min-width: 1024px) {
    .str-chat__main-panel {
      min-width: 0;

      &--thread-open {
        max-width: 55%;
        display: flex;
      }
    }

    .str-chat__thread {
      max-width: 45%;
    }

    .str-chat__channel-header .str-chat__header-hamburger {
      display: none;
    }
  }
}
```

## Chat Client & Connecting User

To communicate with the Stream Chat API the SDK requires a client with an established connection.

> The `useCreateChatClient` hook instantiates the client, connects the user, and cleans up on unmount.

<admonition type="tip">

The `useCreateChatClient` hook accepts an `options` object forwarded to the `StreamChat` constructor. The client is not recreated when `options` changes. If you need to re-create it, set a `key` on the component that calls the hook:

```ts
import { Chat, StreamChatOptions, useCreateChatClient } from 'stream-chat-react';

const App = () => {
  const [timeout, setTimeout] = useState(6000);
  const key = `timeout_${timeout}`;
  return <ChatWithOptions key={key} timeout={timeout} />;
};

const ChatWithOptions = ({ timeout }: StreamChatOptions) => {
  const client = useCreateChatClient({
    apiKey,
    options: { timeout },
    tokenOrProvider: token,
    userData: { id: userId },
  });

  if (!client) return <div>Loading...</div>;
  return <Chat client={client}></Chat>;
};
```

</Admonition>

## Creating a Channel

<Admonition type="info">
Channels are the core of Stream Chat. Once you initialize a channel object, the `Channel` component consumes it and renders the channel UI.
</Admonition>

By default, the Stream Chat API provides support for five different [channel types](/chat/docs/react/channel_features/)
of varying use cases. A channel type is required when creating a channel and dictates the available features and permissions.

The defaults include:

- `messaging`
- `livestream`
- `team`
- `gaming`
- `commerce`

<admonition type="note">

You can also create [custom channel types](/chat/docs/react/channel_features/#creating-a-channel-type/)
and define your own permission sets.

</Admonition>

To create a channel, call `client.channel` with:

- channel type
- channel ID (optional; auto-generated if omitted)
- channel data

```tsx
const channel = client.channel("messaging", {
  image: "https://cdn.com/image.png",
  name: "Just Chatting",
  members: ["dave-matthews", "trey-anastasio"],
  // option to add custom fields
});
```

## Setting Up the Components

> With a client, connected user, and channel, you can compose the core UI components.

### Chat

The [`Chat`](/chat/docs/sdk/react/v13/components/core-components/chat/) component wraps your app and provides the [`ChatContext`](/chat/docs/sdk/react/v13/components/contexts/chat_context/) (including the `StreamChat` client). All other SDK components must be children of `Chat`.

The client instance can be accessed with our custom context hook:

```tsx
import { useChatContext } from "stream-chat-react";

// ...

const { client } = useChatContext();
```

### Channel

The [`Channel`](/chat/docs/sdk/react/v13/components/core-components/channel/) component wraps the logic, state, and UI for a channel. It provides four contexts:

- [`ChannelStateContext`](/chat/docs/sdk/react/v13/components/contexts/channel_state_context/) - stateful data (ex: `messages` or `members`)
- [`ChannelActionContext`](/chat/docs/sdk/react/v13/components/contexts/channel_action_context/) - action handlers (ex: `sendMessage` or `openThread`)
- [`ComponentContext`](/chat/docs/sdk/react/v13/components/contexts/component_context/) - custom component UI overrides (ex: `Avatar` or `Message`)
- [`TypingContext`](/chat/docs/sdk/react/v13/components/contexts/typing_context/) - typing users (ex: `typing`)

### ChannelList

The [`ChannelList`](/chat/docs/sdk/react/v13/components/core-components/channel_list/) renders a channel list and previews. If you use `ChannelList`, don’t pass a `channel` prop to `Channel`—`ChannelList` handles that internally.

### Window

The [`Window`](/chat/docs/sdk/react/v13/components/utility-components/window/) component manages layout changes when opening or closing a `Thread`.

### ChannelHeader

The [`ChannelHeader`](/chat/docs/sdk/react/v13/components/utility-components/channel_header/) displays the active channel’s image and title.

### MessageList

The [`MessageList`](/chat/docs/sdk/react/v13/components/core-components/message_list/) renders messages and consumes the contexts provided by `Channel`. It accepts many optional props for customization.

### MessageInput

The [`MessageInput`](/chat/docs/sdk/react/v13/components/message-input-components/message_input/) component wraps the message composer UI and provides the [`MessageInputContext`](/chat/docs/sdk/react/v13/components/contexts/message_input_context/).

### Thread

The [`Thread`](/chat/docs/sdk/react/v13/components/core-components/thread/) component renders replies for a parent message. It maintains its own state and renders a `MessageList` and `MessageInput`.

### Emojis (picker & autocomplete)

The SDK supports emoji picker and autocomplete integrations. Emoji autocomplete is built on [`emoji-mart`](https://github.com/missive/emoji-mart).

<admonition type="note">

The SDK does not ship with a built-in emoji picker or emoji search index. You'll need to install and configure these yourself. See the [Emoji Picker guide](/chat/docs/sdk/react/v13/guides/customization/emoji_picker/) for setup instructions.

</Admonition>

<admonition type="note">

Read more about customization in our [Theming](/chat/docs/sdk/react/v13/theming/themingv2/) and [UI Cookbook](/chat/docs/sdk/react/v13/guides/customization/) guides.

</Admonition>


---

This page was last updated at 2026-04-21T07:55:44.943Z.

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/sdk/react/v13/basics/getting_started/](https://getstream.io/chat/docs/sdk/react/v13/basics/getting_started/).