---
id: getting_started
title: Getting Started
---

This section provides a high level overview of the library setup, core components, and how they fit together. It's a great starting point and you can follow along in your code editor. For a complete, step-by-step guide in terms setting up a React project or instructions on creating specific files, see our [React Chat tutorial](https://getstream.io/chat/react-chat/tutorial/).

## Your First App with Stream Chat React

Before starting, make sure you have installed `stream-chat-react` (and `stream-chat`), as directed in the
[Installation](./installation.mdx) section.

You'll also need to [register](https://getstream.io/chat/trial/) and create a free tier (for up to 25 MAU) Stream application to access credentials from which you'll be able to [generate a token](https://getstream.io/chat/docs/react/token_generator/) for a user which can access your chat application.

The example below is all the code you'll need to launch a fully functioning chat experience. The [`Chat`](../components/core-components/chat.mdx) and [`Channel`](../components/core-components/channel.mdx) components are React context providers that pass a variety of values to their children, including UI components, stateful data, and action handler functions.

```jsx
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, we provide the following CSS:

```css
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 hook mentioned in the code above (`useCreateChatClient`) handles client instantiation, establishes proper connection and handles cleanups and disconnects for you. If you wish to have more control over how all the previously mentioned is being handled see [Client and User](../guides/client-and-user.mdx) guide.

:::important
The hook `useCreateChatClient` accepts parameter `options`. This is an object forwarded to the `StreamChat` constructor. When the client is created, the first passed `options` value is used, and the client is **not** recreated when the `options` value updates. In most cases it's not a problem, however if you really need to recreate the client with the latest options and reconnect, you can set a `key` on the component that invokes `useCreateChatClient`:

```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>;
};
```

:::

## Creating a Channel

Channels are at the core of Stream Chat. Within a channel you send/receive messages and interact with other users. Once a channel
object has been initialized, the `Channel` component consumes the object and renders your chat app's functionality.

By default, the Stream Chat API provides support for five different [channel types](https://getstream.io/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`

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

To create an instance of a channel, call the `channel` method on your client instance. This method takes the following parameters:

- channel type
- channel ID (optional, will be auto-generated by the backend if not supplied)
- channel data

```jsx
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

Now that we have a client instance, a connected user, and a channel, it's time to look at the core components involved in building
a fully functioning chat application.

### Chat

The [`Chat`](../components/core-components/chat.mdx) component is a React Context provider that wraps the entire Stream Chat application. It provides the [`ChatContext`](../components/contexts/chat-context.mdx) to its children, which includes the `StreamChat` client instance. All other components within the library must be nested as children of `Chat` to maintain proper functionality.

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

```jsx
import { useChatContext } from 'stream-chat-react';

// ...

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

### Channel

The [`Channel`](../components/core-components/channel.mdx) component is a React Context provider that wraps all of the logic, functionality, and UI for an individual chat channel. It provides five separate contexts to its children:

- [`ChannelStateContext`](../components/contexts/channel-state-context.mdx) - stateful data (ex: `messages` or `members`)
- [`ChannelActionContext`](../components/contexts/channel-action-context.mdx) - action handlers (ex: `sendMessage` or `openThread`)
- [`ComponentContext`](../components/contexts/component-context.mdx) - custom component UI overrides (ex: `Avatar` or `Message`)
- [`TypingContext`](../components/contexts/typing-context.mdx) - object of currently typing users (i.e., `typing`)

### ChannelList

The [`ChannelList`](../components/core-components/channel-list.mdx) component renders a list of channels and provides a preview for each. Though the `ChannelList` is essential in many chat apps, it isn't a required piece of the library. If a `ChannelList` component is used, a channel object should not be placed as a prop on the `Channel` component, as the `ChannelList` handles channel setting internally.

### Window

The [`Window`](../components/utility-components/window.mdx) component handles width changes in the main channel to ensure a seamless user experience when opening and closing a `Thread`.

### ChannelHeader

The [`ChannelHeader`](../components/utility-components/channel-header.mdx) displays pertinent information regarding the currently active channel, including image and title.

### MessageList

The [`MessageList`](../components/core-components/message-list.mdx) component renders a list of messages and consumes the various contexts setup from `Channel`. This component accepts a wide variety of optional props for customization needs.

### MessageInput

The [`MessageInput`](../components/message-input-components/message-input.mdx) component is a React Context provider that wraps all of the logic, functionality, and UI for the message input displayed in a channel. It provides the [`MessageInputContext`](../components/contexts/message-input-context.mdx) to its children.

### Thread

The [`Thread`](../components/core-components/thread.mdx) component renders a list of replies tied to a single parent message in a channel's main message list. A `Thread` maintains its own state and renders its own `MessageList` and `MessageInput` components.

### Emojis (picker & autocomplete)

The SDK is equipped with features designed to facilitate seamless integration, enabling developers to effortlessly incorporate [emoji picker](../guides/customization/emoji-picker.mdx) and emoji autocomplete (built on top of [`emoji-mart`](https://github.com/missive/emoji-mart)) functionalities for a comprehensive chat experience.

Make sure to read [_Dropping support for built-in `EmojiPicker`_](../release-guides/upgrade-to-v11.mdx#dropping-support-for-built-in-emojipicker) and [_Dropping support for built-in `EmojiIndex`_](../release-guides/upgrade-to-v11.mdx#dropping-support-for-built-in-emojiindex) release guides for more information.

:::note
Read more about customization in our [Theming](../theming/introduction.mdx) and [Customizing Components](../guides/customization/overview.mdx) guides.
:::
