IconButton

基础表单

基于 Bootstrap 5 的图标按钮组件，用于仅含图标的紧凑操作按钮，支持多种变体、形状、尺寸与状态，可渲染为 button 或 a 元素，并提供切换与加载能力

Component Demo

Basic usage and examples of the IconButton component

基础用法

图标按钮没有可见文字，`label` 会同时设置为 `aria-label` 与 `title`，供屏幕阅读器朗读并显示悬停提示

变体

轮廓变体

形状

尺寸

按钮始终等宽等高，请按尺寸搭配图标大小（sm 推荐 14、默认推荐 18、lg 推荐 22）

禁用状态

切换状态

切换状态由 React 管理（无需引入 Bootstrap JS）：点击自动切换 `active` 类与 `aria-pressed`，受控场景使用 `active`

加载状态

链接按钮

组合使用

`IconButton` 可与 `ButtonGroup`、`Button` 自由组合，例如文字按钮与图标按钮构成的工具栏；即使按钮组被父容器拉伸，图标按钮也始终保持正方形

交互演示

点击收藏

点击触发 3 秒保存

自定义样式

属性组合

API Documentation

Complete API reference for the IconButton component

Props

属性名	类型	默认值	描述
`label`	`string`	-	无障碍标签：设置 `aria-label` 与悬停提示 `title`；图标按钮没有可见文字，建议始终提供
`variant`	`ButtonVariant`	-	按钮视觉变体，对应 Bootstrap 的 `btn-*` 类；不提供时仅应用基础 `btn` 类
`size`	`ButtonSize`	-	按钮大小，可选 `sm` 或 `lg`，按钮始终等宽等高
`shape`	`IconButtonShape`	`'rounded'`	按钮形状：`circle` 应用 `rounded-circle`，`square` 应用 `rounded-0`，`rounded` 保留默认圆角
`active`	`boolean`	-	激活状态：应用 `active` 类；与 `toggle` 配合时作为受控的按压状态
`defaultActive`	`boolean`	`false`	`toggle` 按钮在非受控模式下的初始按压状态
`toggle`	`boolean`	`false`	切换按钮：管理 `aria-pressed` 与 `active` 类，未提供 `active` 时点击自动切换
`disabled`	`boolean`	`false`	是否禁用按钮；渲染为 `a` 时会应用 `disabled` 类、`aria-disabled` 与 `tabIndex=-1`
`loading`	`boolean`	`false`	是否显示加载状态：图标替换为旋转加载指示器，按钮不可交互
`type`	`string`	`'button'`	原生 `type` 属性，仅对 `button` 与 `input` 元素生效
`href`	`string`	-	链接地址，提供后自动渲染为 `a` 元素；可配合 `download`、`rel`、`target` 使用
`download`	`string`	-	提示浏览器下载链接资源而非导航，值为建议的文件名
`rel`	`string`	-	链接与目标资源的关系，例如 `noopener`、`nofollow`
`target`	`string`	-	链接打开的目标窗口，例如 `_blank`、`_self`
`as`	`ElementType`	`'button'`	渲染的根元素，可传入 `a`、`input` 或任意组件
`children`	`ReactNode`	-	按钮内容，通常为单个图标元素（如 lucide-react 图标）
`className`	`string`	-	自定义类名
`...rest`	`ButtonHTMLAttributes`	-	原生 button 元素的所有属性（如 `onClick`、`onFocus` 等）

Type Definitions

IconButtonShape

图标按钮形状类型

type IconButtonShape = 'circle' | 'rounded' | 'square';

IconButtonProps

图标按钮组件属性接口

export interface IconButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  active?: boolean;
  as?: ElementType;
  children?: ReactNode;
  className?: string;
  defaultActive?: boolean;
  disabled?: boolean;
  download?: string;
  href?: string;
  label?: string;
  loading?: boolean;
  rel?: string;
  shape?: IconButtonShape;
  size?: ButtonSize;
  target?: string;
  toggle?: boolean;
  variant?: ButtonVariant;
}