---
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;
    width: 0;

    &--open {
      width: 100%;
    }
  }

  .str-chat-channel {
    width: 100%;
  }

  .str-chat__thread {
    width: 100%;
    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%;
      max-width: 420px;
      position: initial;
      z-index: 0;
    }

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

  @media screen and (min-width: 1024px) {
    .str-chat__thread {
      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 of the previously mentioned is being handled see [Client and User](../guides/client-and-user.mdx) guide.

## 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.
:::
