UIKit React v3

UIKit React

UIKit

React

Home

UIKit

React

This is the new Docs for UIKit v3 for React. To see the previous Docs, click here.

Migration guide

UIKit v3 for React is now available. UIKit v3 has a dependency on Chat SDK v4. Before migrating from v2 to v3, refer to the migration guide of Chat SDK v4 for JavaScript for any breaking changes. The Chat SDK must be updated first before proceeding with the latest version of UIKit.

The biggest change from v2 to v3 is modularization, which allows you to build and customize views at a more minute level. You can execute key messaging functions, such as list channels, through modules. The smart components in v2 have now become modules that consist of separate providers and UI components. While the provider manages all the data of each module, the UI component renders user interfaces that are used to display the view of the module. The provider and UI components exchange data using context hooks. This new architecture allows for easier and more detailed customization.

When migrating from v2 to v3, there are several breaking changes you need to remember. While the properties of the smart components have relatively remained the same in the modules, some arguments in the render props have been removed. Refer to the breaking changes below.

Modules

You can execute key chat functions through various modules provided by UIKit for React. In each module, there is a provider, a set of pre-built UI components, and a context hook that allows access to the provider's data. Refer to the table below to see which modules we provide and the components that make up each module.

Module	Provider	Context hook	UI components
Channel list	ChannelListProvider	useChannelListContext	ChannelListUI ChannelListHeader ChannelPreview
Group channel	ChannelProvider	useChannelContext	ChannelUI ChannelHeader MessageInput MessageList Message FileViewer FrozenNotification RemoveMessageModal TypingIndicator UnreadCount
Group channel settings	ChannelSettingsProvider	useChannelSettingsContext	ChannelSettingsUI ModerationPanel UserPanel ChannelProfile EditDetailsModal exitChannel UserListItem
Open channel	OpenChannelProvider	useOpenChannelContext	OpenChannelUI OpenChannelHeader OpenChannelInput OpenChannelMessageList OpenChannelMessage FrozenChannelNotification
Open channel settings	OpenChannelSettingsProvider	useOpenChannelSettingsContext	OpenChannelSettingsUI ModerationPanel UserPanel OpenChannelProfile EditDetailsModal
Message search	MessageSearchProvider	useMessageSearchContext	MessageSearchUI
Create a channel	CreateChannelProvider	useCreateChannelContext	CreateChannelUI InviteUsers SelectChannelType
Edit user profile	EditUserProfileProvider	useEditUserProfileContext	EditUserProfileUI

Breaking changes

See the breaking changes below for sendbirdSelectors and all modules.

Common changes

The following table shows what common changes were made to the whole UIKit from v2 to v3.

From v2	To v3
npm install sendbird-uikit	npm i @sendbird/uikit-react
sendbird-uikit/dist/index.css	@sendbird/uikit-react/dist/index.css
SendBirdProvider	SendbirdProvider
sendBirdSelectors	sendbirdSelectors
withSendBird()	withSendbird()

sendbirdSelectors

The import path for sendbirdSelectors has changed after the name changed as shown in the code below.

From v2

import { sendBirdSelectors } from 'sendbird-uikit';

To v3

import sendbirdSelectors from '@sendbird/uikit-react/sendbirdSelectors';

Added UIKitMessageHandler

A new interface called UIKitMessageHandler has been added in sendbirdSelectors for handling message events when sending a message. There are three options in the handler as shown in the code below.

const globalStore = useSendbirdStateContext();
const sendUserMessage = sendbirdSelectors.sendUserMessage(globalStore);

sendUserMessage(channel, { message: 'Hello world' })
    .onPending((message) => { })
    .onFailed((error, message) => { })
    .onSucceeded((message) => { })

Added new methods

The folllowing methods have been added for retrieving a channel instance.

Method name	Description
getGetGroupChannel	Specifies a method that returns a `Promise` instance to retrieve a `GroupChannel` instance.
getGetOpenChannel	Specifies a method that returns a `Promise` instance to retrieve an `OpenChannel` instance.

const getGroupChannel = sendbirdSelectors.getGetGroupChannel(globalStore);
getGroupChannel('channel-url')
    .then((channel) => {})
    .catch((error) => {})

const getOpenChannel = sendbirdSelectors.getGetOpenChannel(globalStore);
getOpenChannel('channel-url')
    .then((channel) => {})
    .catch((error) => {})

getSendUserMessage

The getSendUserMessage method and the getOpenChannelSendUserMessage method have combined into one getSendUserMessage. This method generates a function that returns UIKitMessageHandler to send user messages in group channels and open channels.

From v2

const sendUserMessage = sendBirdSelectors.getSendUserMessage(store);
const params = new sdk.UserMessageParams();
sendUserMessage('channel-url', params)
    .then((message) => {})
    .catch((error) => {})

To v3

const sendUserMessage = sendbirdSelectors.getSendUserMessage(globalStore);
sendUserMessage(channel, {} as UserMessageCreateParams)
    .onPending((message) => {})
    .onFailed((error, message) => {})
    .onSucceeded((message) => {})

getSendFileMessage

The getSendFileMessage method and the getOpenChannelSendFileMessage method have combined into one getSendFileMessage. This method generates a function that returns UIKitMessageHandler to send file messages in group channels and open channels.

From v2

const sendFileMessgae = sendBirdSelectors.getSendFileMessage(store);
const params = new sdk.FileMessageParams();
sendFileMessage('channel-url', params)
    .then((message) => {})
    .catch((error) => {})

To v3

const sendFileMessage = sendbirdSelectors.getSendFileMessage(globalStore);
sendFileMessage(channel, {} as FileMessageCreateParams)
    .onPending((message) => {})
    .onFailed((error, message) => {})
    .onSucceeded((message) => {})

getFreezeChannel parameter

The parameter of getFreezeChannel changed from channel-url to GroupChannel or OpenChannel.

From v2

const freezeChannel = sendBirdSelectors.getFreezeChannel(store);
freezeChannel('channel-url')
    .then(() => {})
    .catch((error) => {})

To v3

const freezeChannel = sendbirdSelectors.getFreezeChannel();
freezeChannel(channel: GroupChannel | OpenChannel)
    .then(() => {})
    .catch(() => {})

getUnfreezeChannel parameter

The parameter of getUnfreezeChannel changed from channel-url to GroupChannel or OpenChannel.

From v2

const unfreezeChannel = sendBirdSelectors.getUnfreezeChannel(store);
unfreezeChannel('channel-url')
    .then(() => {})
    .catch((error) => {})

To v3

const unfreezeChannel = sendbirdSelectors.getUnfreezeChannel();
unfreezeChannel(channel: GroupChannel | OpenChannel)
    .then(() => {})
    .catch(() => {})

getCreateGroupChannel

From v2	To v3
getCreateChannel	getCreateGroupChannel

When you call the getCreateGroupChannel method, it returns a Promise instance to create a new group channel.

From v2

const createChannel = sendBirdSelectors.getCreateChannel(store);
const params = new sdk.GroupChannelParams();
createChannel(params)
    .then((channel) => {})
    .catch((error) => {})

To v3

const createGroupChannel = sendbirdSelectors.getCreateGroupChannel(globalStore);
createGroupChannel({} as GroupChannelCreateParams)
    .then((channel) => {})
    .catch((error) => {})

How to create an open channel

When you call the getCreateOpenChannel method, it returns a Promise instance to create a new open channel.

From v2

const createOpenChannel = sendBirdSelectors.getCreateOpenChannel(store);
const params = new sdk.OpenChannelParams();
createOpenChannel(params)
    .then((channel) => {})
    .catch((error) => {})

To v3

const createOpenChannel = sendbirdSelectors.getCreateOpenChannel(globalStore);
createOpenChannel({} as OpenChannelCreateParams)
    .then((channel) => {})
    .catch((error) => {})

getEnterOpenChannel

From v2	To v3
getEnterChannel	getEnterOpenChannel

When you call the getEnterOpenChannel method, it returns a Promise instance to enter an open channel.

From v2

const enterChannel = sendBirdSelectors.getEnterChannel(store);
enterChannel('channel-url')
    .then((channel) => {})
    .catch((error) => {})

To v3

const enterOpenChannel = sendbirdSelectors.getEnterOpenChannel(globalStore);
enterOpenChannel('channel-url')
    .then((channel) => {})
    .catch((error) => {})

getExitOpenChannel

From v2	To v3
getExitChannel	getExitOpenChannel

When you call the getExitOpenChannel method, it returns a Promise instance to exit an open channel.

From v2

const exitChannel = sendBirdSelectors.getExitChannel(store);
exitChannel('channel-url')
    .then((channel) => {})
    .catch((error) => {})

To v3

const exitOpenChannel = sendbirdSelectors.getExitOpenChannel(globalStore);
exitOpenChannel('channel-url')
    .then((channel) => {})
    .catch((error) => {})

getUpdateUserMessage

The getUpdateUserMessage method and the getOpenChannelUpdateUserMessage method have combined into one getUpdateUserMessage. This method generates a function that returns a Promise instance to update user messages in group channels and open channels.

From v2

const updateUserMessage = sendBirdSelectors.getUpdateUserMessage(store);
const params = new sdk.UserMessageParams();
updateUserMessage('channel-url', 'message-id(number)', params)
    .then((message) => {})
    .catch((error) => {})

To v3

const updateUserMessage = sendbirdSelectors.getUpdateUserMessage(globalStore);
updateUserMessage(channel, 'message-id(number)', {} as UserMessageUpdateParams)
    .then((message) => {})
    .catch((error) => {})

getDeleteMessage

The getDeleteMessage method and the getOpenChannelDeleteMessage method have combined into one getDeleteMessage. This method generates a function that returns a Promise instance to delete messages in group channels and open channels.

From v2

const deleteMessage = sendBirdSelectors.getDeleteMessage(store);
deleteMessage('channel-url', message)
    .then((message) => {})
    .catch((error) => {})

To v3

const deleteMessge = sendbirdSelectors.getDeleteMessage(globalStore);
deleteMessage(channel, message)
    .then((message) => {})
    .catch((error) => {})

getResendUserMessage

The getResendUserMessage method and the getOpenChannelResendUserMessage method have combined into one getResendUserMessage. This method generates a function that returns a Promise instance to resend user messages in group channels and open channels.

From v2

const resendUserMessage = sendBirdSelectors.getResendUserMessage(store);
resendUserMessage('channel-url', failedMessage)
    .then((message) => {})
    .catch((error) => {})

To v3

const resendUserMessage = sendbirdSelectors.getResendUserMessage(globalStore);
resendUserMessage(channel, failedMessage)
    .then((message) => {})
    .catch((error) => {})

getResendFileMessage

The getResendFileMessage method and the getOpenChannelResendFileMessage method have combined into one getResendFileMessage. This method generates a function that returns a Promise instance to resend file messages in group channels and open channels.

From v2

const resendFileMessage = sendBirdSelectors.getResendFileMessage(store);
resendFileMessage('channel-url', failedMessage)
    .then((message) => {})
    .catch((error) => {})

To v3

const resendFileMessage = sendbirdSelectors.getResendFileMessage(globalStore);
resendFileMessage(channel, failedMessage)
    .then((message) => {})
    .catch((error) => {})

ChannelList

The ChannelList smart component has now become ChannelList module. See the codes below on how to import the new channel list module.

From v2

import { ChannelList } from 'sendbird-uikit';

To v3

import ChannelList from '@sendbird/uikit-react/ChannelList'
// Or use this code.
import { ChannelList } from '@sendbird/uikit-react'

Added new props

The following table lists properties that were added to the ChannelList module.

Property name	Type	Description
renderPlaceHolderError	ReactElement	Renders a customized placeholder for error messages in the channel list. (Default: `null`)
renderPlaceHolderLoading	ReactElement	Renders a customized placeholder for loading messages in the channel list. (Default: `null`)
renderPlaceHolderEmptyList	ReactElement	Renders a customized placeholder message for when the channel list is empty. (Default: `null`)

Channel

The Channel smart component has now become Channel module. See the codes below on how to import the new group channel module.

From v2

import { Channel } from 'sendbird-uikit';

To v3

import Channel from '@sendbird/uikit-react/Channel'
// Or use this code.
import { Channel } from '@sendbird/uikit-react'

Renamed props

The following table lists properties of the Channel module that were renamed.

From v2	To v3
useReaction	isReactionEnabled
useMessageGrouping	isMessageGroupingEnabled

Removed render props

The following render props have been removed from UIKit v3:

renderCustomMessage
renderChatItem

renderMessage

See the code below on how to implement message-related actions in a group channel using the sendbirdSelectors component.

From v2

import { Channel, SendbirdProvider } from 'sendbird-uikit';

const MyCustomChatMessage = ({ message, onDeleteMessage, onUpdateMessage }) => (
    <div>
        {message.message}
        <button
            onClick={() => {
                const callback = () => { console.warn('message deleted'); }
                onDeleteMessage(message, callback);
            }}
        >
            Delete message.
        </button>
        <button
            onClick={() => {
                const updatedMessage = Math.random().toString();
                const callback = () => { console.warn('message updated'); }
                onUpdateMessage(message.messageId, updatedMessage, callback);
            }}
        >
            Update message.
        </button>
    </div>
);

const App = () => (
    <SendbirdProvider appId={appId} userId={userId}>
        <div style={{ height: '500px' }}>
            <Channel channelUrl={channelUrl} renderChatItem={MyCustomChatMessage} />
        </div>
    </SendbirdProvider>
);

To v3

<Channel
  renderMessage={MyFileMessageComponent}
/>
const MyFileMessageComponent = ({ message, chainTop, chainBottom }) => {
  const {
    currentGroupChannel,
    scrollToMessage,
  } = useChannelContext();
  const globalStore = useSendbirdStateContext();
  // Use sendbirdSelectors and globalStore to implement onDeleteMessage, onUpdateMessage, onResendMessage.
  const deleteFileMessage = sendbirdSelectors.getDeleteMessage(globalStore);
  if (message.messageType === 'file') {
    return (
      <div className="custom-file-message">
        <button
          className="custom-file-message__delete-button"
          onClick={deleteFileMessage(currentGroupChannel, message)}
        />
            Implement your code here.
      </div>
    )
  }
  return null;
}

Function signature

Render prop	From v2	To v3
renderMessageInput	({ channel, user, disabled, quoteMessage }) => React.ReactNode	() => React.ReactNode
renderChannelHeader	renderChatHeader?: ({ channel, user }) => React.ReactNode	renderChannelHeader?: () => React.ReactNode

How to render message input

See the code below on how to render the MessageInput component with useChannel context hook and implement message-related actions in the channel using the sendbirdSelectors component.

<Channel
  renderMessageInput={MyMessageInput}
/>
const MyMessageInput = ({message, chainTop, chainBottom }) => {
  const {
    currentGroupChannel,
  } = useChannelContext();
  const globalStore = useSendbirdStateContext();
  // Use `sendbirdSelectors` and `globalStore` to implement `getSendUserMessage` and `getSendFileMessage`.
  const sendUserMessage = sendbirdSelectors.getSendUserMessage(globalStore);
  return (
    //...
  );
}

How to render header

See the code below on how to render channel header with useChannel.

<Channel
  renderMessageInput={MyChannelHEader}
/>
const MyChannelHEader = () => {
  const {
    currentGroupChannel,
  } = useChannelContext();
  const globalStore = useSendbirdStateContext();
  const user = globalStore?.stores?.userStore?.user;
  return (
    //...
  );
}

Added new props

The following table lists properties that were added to the Channel module.

Property name	Type	Description
renderPlaceholderLoader	ReactElement	Renders a customized placeholder for loading messages in the channel. (Default: `null`)
renderPlaceholderInvalid	ReactElement	Renders a customized placeholder for invalid channel state. (Default: `null`)
renderPlaceholderEmpty	ReactElement	Renders a customized placeholder for an empty channel. (Default: `null`)
renderChannelHeader	ReactElement	Renders a customized channel header component. (Default: `null`)
renderMessage	ReactElement	Renders a customized message view in the channel. (Default: `null`)
renderMessageInput	ReactElement	Renders a customized message input component. (Default: `null`)
renderTypingIndicator	ReactElement	Renders a customized typing indicator component. (Default: `null`)
renderCustomSeperator	ReactElement	Renders a customized date separator view in the message list component. (Default: `null`)

ChannelSettings

The ChannelSettings smart component has now become ChannelSettings module. See the codes below on how to import the new group channel settings module.

From v2

import { ChannelSettings } from 'sendbird-uikit';

To v3

import ChannelSettings from '@sendbird/uikit-react/ChannelSettings'
// Or use this code.
import { ChannelSettings } from '@sendbird/uikit-react'

Function signature

Render prop	From v2	To v3
renderChannelProfile	({ channel }) => React.ReactNode	() => React.ReactNode

How to render channel profile

See the code below on how to render channel header with useChannelSettingsContext.

<ChannelSettings
  renderChannelProfile={MyChannelProfile}
/>
const MyChannelProfile = () => {
  const { channel } = useChannelSettingsContext();
  return (...);
}

Added new props

The following table lists properties that were added to the ChannelSettings module.

Property name	Type	Description
renderPlaceHolderError	ReactElement	Renders a customized placeholder for error messages that occur in the channel settings menu. (Default: `null`)
renderModerationPanel	ReactElement	Renders a customized view of the moderation panel that displays the moderation tools for channel operators. (Default: `null`)
renderexitChannel	ReactElement	Renders a customized leave channel button in the settings module. (Default: `null`)

OpenChannel

The OpenChannel smart component has now become OpenChannel module. See the codes below on how to import the new open channel module.

From v2

import { OpenChannel } from 'sendbird-uikit';

To v3

import OpenChannel from '@sendbird/uikit-react/OpenChannel'
// Or use this code.
import { OpenChannel } from '@sendbird/uikit-react'

Function signature

Render prop	From v2	To v3
renderChannelTitle	({channel, user}) => React.ReactNode	() => React.ReactNode
renderMessageInput	({channel, user, disabled}) => React.ReactNode	() => React.ReactNode

Property names

From v2	To v3
renderCustomMessage	renderMessage
experimentalMessageLimit	messageLimit
useReaction	isReactionEnabled
useMessageGrouping	isMessageGroupingEnabled

How to render message, channel title, and message input

See the code below on how to render the MessageInput component with useOpenChannelContext context hook and implement message-related actions in the channel using the sendbirdSelectors component.

<OpenChannel
  renderInput={MyMessage}
/>
const MyMessageInput = () => {
  // Use `useOpenChannelContext` to access current channel.
  const {
    currentOpenChannel,
  } = useOpenChannelContext();
  const globalStore = useSendbirdStateContext();
  // Use `sendbirdSelectors` and `globalStore` to implement `getSendUserMessage` and `getSendFileMessage`.
  const sendMessage = sendbirdSelectors.getSendUserMessage(globalStore);
  return (
    //...
  );
}

Added new props

The following table lists properties that were added to the OpenChannel module.

Property name	Type	Description
renderMessage	ReactElement	Renders a customized message view in the channel. (Default: `null`)
renderHeader	ReactElement	Renders a customized channel header component. (Default: `null`)
renderInput	ReactElement	Renders a customized message input component. (Default: `null`)
renderPlaceholderEmptyList	ReactElement	Renders a customized placeholder for an empty channel. (Default: `null`)
renderPlaceHolderError	ReactElement	Renders a customized placeholder for error messages that occur in the channel. (Default: `null`)
renderPlaceholderLoading	ReactElement	Renders a customized placeholder for loading messages in the channel. (Default: `null`)

OpenChannelSettings

The OpenChannelSettings smart component has now become OpenChannelSettings module. See the codes below on how to import the new open channel settings module.

From v2

import { OpenChannelSettings } from 'sendbird-uikit';

To v3

import OpenChannelSettings from '@sendbird/uikit-react/OpenChannelSettings'
// Or use this code.
import { OpenChannelSettings } from '@sendbird/uikit-react'

Replaced renderChannelProfile

From v2	To v3
renderChannelProfile	renderOperatorUI, renderParticipantList

Added new props

The following table lists properties that were added to the OpenChannelSettings module.

Property name	Type	Description
renderOperatorUI	ReactElement	Renders a customized view of the channel settings for operators. (Default: `null`)
renderParticipantList	ReactElement	Renders a customized view of the channel settings for non-operator members. (Default: `null`)

MessageSearch

The MessageSearch smart component has now become MessageSearch module. See the codes below on how to import the new message search module.

From v2

import { MessageSearch } from 'sendbird-uikit';

To v3

import MessageSearch from '@sendbird/uikit-react/MessageSearch'
// Or use this code.
import { MessageSearch } from '@sendbird/uikit-react'

Added new props

The following table lists properties that were added to the MessageSearch module.

Property name	Type	Description
renderPlaceHolderError	ReactElement	Renders a customized placeholder for error messages that occur in the search result. (Default: `null`)
renderPlaceholderLoading	ReactElement	Renders a customized placeholder for loading messages in the search result. (Default: `null`)
renderPlaceHolderNoString	ReactElement	Renders a customized placeholder for when there are no messages that match the search query.
renderPlaceholderEmptyList	ReactElement	Renders a customized placeholder for an empty list of search results. (Default: `null`)

Added new modules

In v3, CreateChannel module and EditUserProfile module have been added. Go to the Create a channel page and Edit user profile page to learn more.