SocialButton

social-button

提供带品牌标识的第三方登录按钮，含加载态

用法

基础用法

传 provider 即得品牌 logo + 默认登录文案。

tsx

<SocialButton provider="wechat" />

国内 / 国际平台

内置微信/支付宝/QQ/微博与 GitHub/Google/Apple/X 等品牌。

tsx

<>
  <SocialButton provider="wechat" />
  <SocialButton provider="alipay" />
  <SocialButton provider="github" />
  <SocialButton provider="google" />
</>

填充变体

variant=solid 用品牌色填充（黑白系品牌随主题前景）。

tsx

<>
  <SocialButton provider="wechat" variant="solid" />
  <SocialButton provider="github" variant="solid" />
</>

纯 logo 方钮

shape=icon 只渲染品牌 logo，适合紧凑工具条。

tsx

<>
  <SocialButton provider="wechat" shape="icon" />
  <SocialButton provider="alipay" shape="icon" variant="solid" />
</>

自定义平台（枚举外的 IdP）

provider 传对象即可接入自建 OIDC / 未内置的品牌，皮肤与内置品牌完全一致。不传 brandColor 即黑白档。

tsx

// 必须提到模块作用域：组件是 memo 的，内联对象会让 memo 失效
const KEYCLOAK: SocialBrand = { label: "企业 SSO", icon: <LockIcon /> };

<SocialButton provider={KEYCLOAK} />

尺寸 / 加载 / 禁用

size 三档；loading 转圈并禁用，disabled 屏蔽交互。

tsx

<>
  <SocialButton provider="wechat" size="sm" />
  <SocialButton provider="wechat" size="lg" />
  <SocialButton provider="github" loading />
  <SocialButton provider="google" disabled />
</>

何时用

第三方账号登录/绑定入口（微信、支付宝、QQ、微博、GitHub、Google、Apple、X、Discord、GitLab）。内置品牌 logo、默认文案与品牌色，无需自己接 simple-icons。枚举之外的平台（自建 OIDC / Keycloak / Authentik / Okta / 企业 SSO，以及未内置的品牌）给 provider 传对象即可，见下方「自定义平台」。普通操作按钮用 Button；需要把多个登录方式编成一组用 ButtonGroup 包裹。

导入

import { SocialButton } from "@hulianui/ui"

Props

继承原生 <button> 属性（除 children 受控覆盖外）。

名称	类型	默认	说明
provider*	`"wechat" ｜ "alipay" ｜ "qq" ｜ "weibo" ｜ "github" ｜ "google" ｜ "apple" ｜ "x" ｜ "discord" ｜ "gitlab" ｜ SocialBrand`	-	第三方平台，决定 logo、默认文案与品牌色。传对象即接入枚举外的平台，字段见下表
variant	`"solid" ｜ "outline"`	`"outline"`	solid=品牌色填充（黑白品牌随主题前景）；outline=描边中性底 + 品牌色 logo（推荐）
shape	`"button" ｜ "icon"`	`"button"`	button=带文案；icon=纯 logo 方钮
size	`"sm" ｜ "md" ｜ "lg"`	`"md"`	尺寸
loading	`boolean`	`false`	提交中：logo 替换为转圈并禁用
className	`string`	-	透传根节点类名

SocialBrand（自定义平台）

provider 传对象时的字段。皮肤（尺寸/形态/loading/按压/焦点环）与内置品牌完全共用。

名称	类型	默认	说明
icon*	`ReactNode`	-	品牌 logo。内联 `<svg>` / `<img>` / 图标组件皆可，会被约束到当前 `size` 的图标尺寸
label*	`string`	-	品牌名。用于默认文案（「{label}登录」）与 `shape="icon"` 时的 `aria-label`
brandColor	`string`	-	品牌主色。outline 时给 logo 着色、solid 时作按钮底色；不传即黑白档，与内置 GitHub/X/Apple 同处方

Events

事件	类型	说明
onClick	`(e: MouseEvent<HTMLButtonElement>) => void`	透传原生点击回调（发起第三方登录/绑定）

Slots

插槽	类型	说明
children	`ReactNode`	覆盖默认文案（如「使用微信登录」→「微信」）

禁忌 / 坑

自定义品牌对象必须提到模块作用域（或 useMemo 起来）。本组件是 memo 的，写成 provider={{ ... }} 内联对象字面量，每次渲染都是新引用，memo 当场失效。
别等着枚举补全：simple-icons 已应法务要求下架 Microsoft / LinkedIn / Slack / 飞书等 logo，这些在库里无法内置；自建 IdP 更是穷举不完。碰到没有的平台直接走 SocialBrand，不要因为「一组 4 个里坏 2 个」而整组退回 Button 自己塞 SVG。
loading 会自动禁用按钮，无需额外传 disabled。
github/x/apple 黑白系品牌的 solid 态会跟随主题前景色，避免在暗色下不可见——不要硬写品牌黑覆盖。自定义品牌不传 brandColor 时同档。

Playground

providervariantshape

<SocialButton provider="wechat" />

用法

基础用法

传 provider 即得品牌 logo + 默认登录文案。

tsx

<SocialButton provider="wechat" />

国内 / 国际平台

内置微信/支付宝/QQ/微博与 GitHub/Google/Apple/X 等品牌。

tsx

<>
  <SocialButton provider="wechat" />
  <SocialButton provider="alipay" />
  <SocialButton provider="github" />
  <SocialButton provider="google" />
</>

填充变体

variant=solid 用品牌色填充（黑白系品牌随主题前景）。

tsx

<>
  <SocialButton provider="wechat" variant="solid" />
  <SocialButton provider="github" variant="solid" />
</>

纯 logo 方钮

shape=icon 只渲染品牌 logo，适合紧凑工具条。

tsx

<>
  <SocialButton provider="wechat" shape="icon" />
  <SocialButton provider="alipay" shape="icon" variant="solid" />
</>

自定义平台（枚举外的 IdP）

provider 传对象即可接入自建 OIDC / 未内置的品牌，皮肤与内置品牌完全一致。不传 brandColor 即黑白档。

tsx

// 必须提到模块作用域：组件是 memo 的，内联对象会让 memo 失效
const KEYCLOAK: SocialBrand = { label: "企业 SSO", icon: <LockIcon /> };

<SocialButton provider={KEYCLOAK} />

尺寸 / 加载 / 禁用

size 三档；loading 转圈并禁用，disabled 屏蔽交互。

tsx

<>
  <SocialButton provider="wechat" size="sm" />
  <SocialButton provider="wechat" size="lg" />
  <SocialButton provider="github" loading />
  <SocialButton provider="google" disabled />
</>

何时用

Props

继承原生 <button> 属性（除 children 受控覆盖外）。

名称	类型	默认	说明
provider*	`"wechat" ｜ "alipay" ｜ "qq" ｜ "weibo" ｜ "github" ｜ "google" ｜ "apple" ｜ "x" ｜ "discord" ｜ "gitlab" ｜ SocialBrand`	-	第三方平台，决定 logo、默认文案与品牌色。传对象即接入枚举外的平台，字段见下表
variant	`"solid" ｜ "outline"`	`"outline"`	solid=品牌色填充（黑白品牌随主题前景）；outline=描边中性底 + 品牌色 logo（推荐）
shape	`"button" ｜ "icon"`	`"button"`	button=带文案；icon=纯 logo 方钮
size	`"sm" ｜ "md" ｜ "lg"`	`"md"`	尺寸
loading	`boolean`	`false`	提交中：logo 替换为转圈并禁用
className	`string`	-	透传根节点类名

SocialBrand（自定义平台）

provider 传对象时的字段。皮肤（尺寸/形态/loading/按压/焦点环）与内置品牌完全共用。

名称	类型	默认	说明
icon*	`ReactNode`	-	品牌 logo。内联 `<svg>` / `<img>` / 图标组件皆可，会被约束到当前 `size` 的图标尺寸
label*	`string`	-	品牌名。用于默认文案（「{label}登录」）与 `shape="icon"` 时的 `aria-label`
brandColor	`string`	-	品牌主色。outline 时给 logo 着色、solid 时作按钮底色；不传即黑白档，与内置 GitHub/X/Apple 同处方

事件

类型

说明

onClick

(e: MouseEvent<HTMLButtonElement>) => void

透传原生点击回调（发起第三方登录/绑定）

插槽

类型

说明

children

ReactNode

覆盖默认文案（如「使用微信登录」→「微信」）

禁忌 / 坑

自定义品牌对象必须提到模块作用域（或 useMemo 起来）。本组件是 memo 的，写成 provider={{ ... }} 内联对象字面量，每次渲染都是新引用，memo 当场失效。

别等着枚举补全：simple-icons 已应法务要求下架 Microsoft / LinkedIn / Slack / 飞书等 logo，这些在库里无法内置；自建 IdP 更是穷举不完。碰到没有的平台直接走 SocialBrand，不要因为「一组 4 个里坏 2 个」而整组退回 Button 自己塞 SVG。

loading 会自动禁用按钮，无需额外传 disabled。

github/x/apple 黑白系品牌的 solid 态会跟随主题前景色，避免在暗色下不可见——不要硬写品牌黑覆盖。自定义品牌不传 brandColor 时同档。

SocialButton

用法

基础用法

国内 / 国际平台

填充变体

纯 logo 方钮

自定义平台（枚举外的 IdP）

尺寸 / 加载 / 禁用

何时用

导入

Props

SocialBrand（自定义平台）

Events

Slots

禁忌 / 坑

相关

Playground

SocialButton

用法

基础用法

国内 / 国际平台

填充变体

纯 logo 方钮

自定义平台（枚举外的 IdP）

尺寸 / 加载 / 禁用

何时用

导入

Props

SocialBrand（自定义平台）

Events

Slots

禁忌 / 坑

相关

Playground