# agora-rtc-react

**Repository Path**: agoraio-community/agora-rtc-react

## Basic Information

- **Project Name**: agora-rtc-react
- **Description**: Agora RTC React SDK
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2023-07-10
- **Last Updated**: 2025-11-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# agora-rtc-react

[![Build Status](https://github.com/agoraio-extensions/agora-rtc-react/actions/workflows/build.yml/badge.svg)](https://github.com/agoraio-extensions/agora-rtc-react/actions/workflows/build.yml)

[![npm-version](https://img.shields.io/npm/v/agora-rtc-react.svg)](https://www.npmjs.com/package/agora-rtc-react)
[![minified-size](https://img.shields.io/bundlephobia/minzip/agora-rtc-react)](https://bundlephobia.com/package/agora-rtc-react)

[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg?maxAge=2592000)](http://commitizen.github.io/cz-cli/)
[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-brightgreen.svg?maxAge=2592000)](https://conventionalcommits.org)
[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)

[English](./README.md) | 简体中文

agora-rtc-react 可以让你在 React 应用中更便捷的使用 [agora-rtc-sdk-ng](https://www.npmjs.com/package/agora-rtc-sdk-ng)。

# 安装方法

```bash
npm i agora-rtc-react
```

# 示例

Here is the first one to get you started:

```tsx
import AgoraRTC from "agora-rtc-sdk-ng";
import { AgoraRTCProvider } from "agora-rtc-react";

const Client = ({ children }) => {
  return (
    <AgoraRTCProvider client={AgoraRTC.createClient({ mode: "rtc", codec: "vp8" })}>
      {children}
    </AgoraRTCProvider>
  );
};
const root = createRoot(document.getElementById("container"));
root.render(<Client />);
```

This example will render Agora Client into a container on the page.

# 一些例子

### [访问更多示例](https://agoraio-extensions.github.io/agora-rtc-react/basic/)

### 或者在本地运行示例,请通过下述操作步骤:

- 添加 `.env.local` 文件到每个 example 文件夹中, 并且填写 Agora 账号信息。你可以参考 `.env.example`。
- 执行 `pnpm start` 。

# Components

- [`RemoteVideoTrack`](https://github.com/AgoraIO-Extensions/agora-rtc-react/tree/main/packages/agora-rtc-react/docs/components/RemoteVideoTrack.zh-CN.mdx) &mdash; 该组件用于播放远端用户的视频轨道，并且不支持指定播放设备。

- [`RemoteUser`](https://github.com/AgoraIO-Extensions/agora-rtc-react/tree/main/packages/agora-rtc-react/docs/components/RemoteUser.zh-CN.mdx) &mdash; 该组件用于播放远端用户的视频和音频轨道，并且仅支持指定使用的音频设备、不支持指定使用的视频设备。

- [`RemoteAudioTrack`](https://github.com/AgoraIO-Extensions/agora-rtc-react/tree/main/packages/agora-rtc-react/docs/components/RemoteAudioTrack.zh-CN.mdx) &mdash; 该组件用于播放远端用户的音频轨道，并且支持指定播放设备。

- [`LocalVideoTrack`](https://github.com/AgoraIO-Extensions/agora-rtc-react/tree/main/packages/agora-rtc-react/docs/components/LocalVideoTrack.zh-CN.mdx) &mdash; 该组件用于播放本地视频轨道，播放设备为用户在浏览器中选择的设备。

- [`LocalUser`](https://github.com/AgoraIO-Extensions/agora-rtc-react/tree/main/packages/agora-rtc-react/docs/components/LocalUser.zh-CN.mdx) &mdash; 该组件用于播放本地用户的摄像头视频轨道和麦克风音频轨道，播放设备为用户在浏览器中选择的设备。

- [`LocalAudioTrack`](https://github.com/AgoraIO-Extensions/agora-rtc-react/tree/main/packages/agora-rtc-react/docs/components/LocalAudioTrack.zh-CN.mdx) &mdash; 该组件用于播放本地音频轨道，播放设备为用户在浏览器中选择的设备。

- [`AgoraRTCScreenShareProvider`](https://github.com/AgoraIO-Extensions/agora-rtc-react/tree/main/packages/agora-rtc-react/docs/components/AgoraRTCScreenShareProvider.zh-CN.mdx) &mdash; 该组件向子组件<a href="https://react.dev/learn/passing-data-deeply-with-context">提供 Context</a>，让 children 内的各个组件都能读取你传入的用于屏幕共享的 client 属性。

- [`AgoraRTCProvider`](https://github.com/AgoraIO-Extensions/agora-rtc-react/tree/main/packages/agora-rtc-react/docs/components/AgoraRTCProvider.zh-CN.mdx) &mdash; 该组件向子组件<a href="https://react.dev/learn/passing-data-deeply-with-context">提供 Context</a>，让 children 内的各个组件都能读取你传入的 client 属性。

# Hooks

- [`useVolumeLevel`](https://github.com/AgoraIO-Extensions/agora-rtc-react/tree/main/packages/agora-rtc-react/docs/hooks/useVolumeLevel.zh-CN.mdx) &mdash; 用于自动获取音频轨道音量级别，自动获取的频率为每秒一次。

- [`useTrackEvent`](https://github.com/AgoraIO-Extensions/agora-rtc-react/tree/main/packages/agora-rtc-react/docs/hooks/useTrackEvent.zh-CN.mdx) &mdash; 用于监听本地轨道对象或远端轨道对象的特定事件。

- [`useRemoteVideoTracks`](https://github.com/AgoraIO-Extensions/agora-rtc-react/tree/main/packages/agora-rtc-react/docs/hooks/useRemoteVideoTracks.zh-CN.mdx) &mdash; 用于自动订阅和获取远端用户视频轨道。

- [`useRemoteUsers`](https://github.com/AgoraIO-Extensions/agora-rtc-react/tree/main/packages/agora-rtc-react/docs/hooks/useRemoteUsers.zh-CN.mdx) &mdash; 用于获取远端用户列表。

- [`useRemoteUserTrack`](https://github.com/AgoraIO-Extensions/agora-rtc-react/tree/main/packages/agora-rtc-react/docs/hooks/useRemoteUserTrack.zh-CN.mdx) &mdash; 用于获取远端用户音视频轨道。

- [`useRemoteAudioTracks`](https://github.com/AgoraIO-Extensions/agora-rtc-react/tree/main/packages/agora-rtc-react/docs/hooks/useRemoteAudioTracks.zh-CN.mdx) &mdash; 用于自动订阅和获取远端用户音频轨道。

- [`useRTCClient`](https://github.com/AgoraIO-Extensions/agora-rtc-react/tree/main/packages/agora-rtc-react/docs/hooks/useRTCClient.zh-CN.mdx) &mdash; 用于获取 IAgoraRTCClient 对象。

- [`usePublish`](https://github.com/AgoraIO-Extensions/agora-rtc-react/tree/main/packages/agora-rtc-react/docs/hooks/usePublish.zh-CN.mdx) &mdash; 用于发布本地轨道。当组件准备好时发布，当组件卸载时取消发布。

- [`useNetworkQuality`](https://github.com/AgoraIO-Extensions/agora-rtc-react/tree/main/packages/agora-rtc-react/docs/hooks/useNetworkQuality.zh-CN.mdx) &mdash; 用于获取本地用户网络质量。

- [`useLocalScreenTrack`](https://github.com/AgoraIO-Extensions/agora-rtc-react/tree/main/packages/agora-rtc-react/docs/hooks/useLocalScreenTrack.zh-CN.mdx) &mdash; 用于创建本地屏幕共享的视频轨道。

- [`useLocalMicrophoneTrack`](https://github.com/AgoraIO-Extensions/agora-rtc-react/tree/main/packages/agora-rtc-react/docs/hooks/useLocalMicrophoneTrack.zh-CN.mdx) &mdash; 用于创建本地麦克风音频轨道。你可以在不同组件中调用该方法以创建多个轨道。如果要在多个组件中访问同一个轨道，请确保在多个组件中都传入同一个轨道对象。

- [`useLocalCameraTrack`](https://github.com/AgoraIO-Extensions/agora-rtc-react/tree/main/packages/agora-rtc-react/docs/hooks/useLocalCameraTrack.zh-CN.mdx) &mdash; 用于创建本地摄像头视频轨道。你可以在不同组件中调用该方法以创建多个轨道。如果要在多个组件中访问同一个轨道，请确保在多个组件中都传入同一个轨道对象。

- [`useJoin`](https://github.com/AgoraIO-Extensions/agora-rtc-react/tree/main/packages/agora-rtc-react/docs/hooks/useJoin.zh-CN.mdx) &mdash; 用于加入频道。当组件准备好时加入频道，当组件卸载时自动离开频道。

- [`useIsConnected`](https://github.com/AgoraIO-Extensions/agora-rtc-react/tree/main/packages/agora-rtc-react/docs/hooks/useIsConnected.zh-CN.mdx) &mdash; 用于获取 SDK 是否连接到服务器。

- [`useCurrentUID`](https://github.com/AgoraIO-Extensions/agora-rtc-react/tree/main/packages/agora-rtc-react/docs/hooks/useCurrentUID.zh-CN.mdx) &mdash; 用于获取当前用户 UID 。

- [`useConnectionState`](https://github.com/AgoraIO-Extensions/agora-rtc-react/tree/main/packages/agora-rtc-react/docs/hooks/useConnectionState.zh-CN.mdx) &mdash; 用于获取详细的 SDK 连接状态。

- [`useClientEvent`](https://github.com/AgoraIO-Extensions/agora-rtc-react/tree/main/packages/agora-rtc-react/docs/hooks/useClientEvent.zh-CN.mdx) &mdash; 用于监听 IAgoraRTCClient 对象的指定事件。

- [`useAutoPlayVideoTrack`](https://github.com/AgoraIO-Extensions/agora-rtc-react/tree/main/packages/agora-rtc-react/docs/hooks/useAutoPlayVideoTrack.zh-CN.mdx) &mdash; 用于自动播放本地或远端视频轨道。

- [`useAutoPlayAudioTrack`](https://github.com/AgoraIO-Extensions/agora-rtc-react/tree/main/packages/agora-rtc-react/docs/hooks/useAutoPlayAudioTrack.zh-CN.mdx) &mdash; 用于自动播放本地或远端音频轨道。

# License

MIT © [Agora.io](https://github.com/AgoraIO)