---
title: "@xid-kit/react"
description: "面向客户应用的 React 19 provider、hooks、控制组件和 Hosted UI 构建块。"
locale: "zh-Hans"
---

> Documentation Index
> Fetch the locale documentation index at: https://xid.dev/zh-hans/llms.txt
> Use this file to discover all available pages before exploring further.

# @xid-kit/react

## Provider 配置

```tsx
import { XidProvider } from '@xid-kit/react'

export function AppProviders({ children }: { children: React.ReactNode }) {
  return (
<XidProvider publishableKey="pk_live_..." apiUrl="https://xid.dev">
  {children}
</XidProvider>
  )
}
```

## Hooks

| Hook | 返回值 |
| --- | --- |
| `useAuth` | isLoaded、isSignedIn、userId、signOut、getToken |
| `useUser` | isLoaded、isSignedIn、user: XidUser \| null |
| `useSession` | isLoaded、isSignedIn、session: XidSession \| null |
| `useSessionList` | isLoaded、sessions、用于多会话切换器的 setActive |
| `useSignIn` | Hosted Auth 登录流程辅助工具 |
| `useOrganization` | isLoaded、organization: XidOrganization \| null、membership |
| `useOrganizationList` | isLoaded、用于组织切换器 UI 的 userMemberships |
| `useAPIKeys` | 用于控制台嵌入的 Management API 密钥列表和操作 |
| `useXidContext` | 原始 XidContextValue（高级用法；优先使用上方的类型化 hooks） |

## 控制组件

| 组件 | Props 类型 | 用途 |
| --- | --- | --- |
| `SignedIn` | `SignedInProps` | 仅在会话已加载且已登录时渲染子节点 |
| `SignedOut` | `SignedOutProps` | 仅在已加载且未登录时渲染子节点 |
| `Protect` | `ProtectProps` | 带可选后备 UI 的权限和角色校验门 |
| `XidLoaded` | `XidLoadedProps` | SDK 水合完成后渲染子节点（isLoaded 为 true） |
| `XidLoading` | `XidLoadingProps` | SDK 仍在加载时渲染子节点（isLoaded 为 false） |
| `XidFailed` | `XidFailedProps` | SDK 加载因不可恢复错误失败时渲染子节点（status 为 error） |
| `XidDegraded` | `XidDegradedProps` | SDK 已加载但处于降级状态时渲染子节点（status 为 degraded） |
| `AuthenticateWithRedirectCallback` | `AuthenticateWithRedirectCallbackProps` | OAuth 重定向 callback 处理器：重新加载会话状态，并重定向到 afterSignInUrl 或调用 onSuccess |
| `RedirectToSignIn` | `RedirectToSignInProps` | 挂载后立即重定向到登录页面 |
| `RedirectToSignUp` | `RedirectToSignUpProps` | 挂载后立即重定向到注册页面 |
| `RedirectToUserProfile` | `RedirectToUserProfileProps` | 挂载后立即重定向到用户资料页面 |
| `RedirectToOrganizationProfile` | `RedirectToOrganizationProfileProps` | 挂载后立即重定向到组织资料页面 |
| `RedirectToCreateOrganization` | `RedirectToCreateOrganizationProps` | 挂载后立即重定向到创建组织页面 |
| `SignInButton` | `SignInButtonProps` | 点击时跳转到登录 URL 的无样式按钮 |
| `SignUpButton` | `SignUpButtonProps` | 点击时跳转到注册 URL 的无样式按钮 |
| `SignOutButton` | `SignOutButtonProps` | 点击时调用 signOut 的无样式按钮 |

## UI 组件

| 组件 | 使用 |
| --- | --- |
| `SignIn` | 嵌入式登录面板（Hosted Auth） |
| `SignUp` | 嵌入式注册面板 |
| `UserAvatar` | 带首字母后备的用户头像图片 |
| `UserButton` | 带会话切换和登出功能的头像菜单 |
| `UserProfile` | 账户安全与资料管理 |
| `OrganizationSwitcher` | 当前组织选择器 |
| `OrganizationProfile` | 成员、角色和 SSO 管理嵌入组件 |
| `CreateOrganization` | 组织创建流程 |
| `OrganizationList` | 用于切换器 UI 的用户组织列表 |

## 尚未实现

以下内容在公开路线图中，但当前包尚未导出。请勿假设在本版本中可用。

| 符号 | 设计承诺 |
| --- | --- |
| `GoogleOneTap` | 一键登录嵌入组件 |
| `Waitlist` | 候补名单注册门控组件 |
| 计费组件 | 用量和套餐管理嵌入组件 |
| `useReverification` | Step-up 认证 hook |

## 外观

将 `appearance` 传给 `XidProvider` 以覆盖白标嵌入的 CSS 变量。所有用户可见字符串使用 Lingui 运行时描述符；`Appearance`、`AppearanceVariables` 和 `AppearanceElements` 类型已导出供类型化覆盖使用。

Source: https://xid.dev/zh-hans/sdks/react/index.mdx