常用的操作按钮。
基础用法
使用 type, plain, round, dashed 和 circle 来定义按钮的样式。
"use client";import { ElButton } from "@/components/element-plus/button";import { Check, Delete, Edit, Message, Search, Star } from "@/components/element-plus/generated/icons";import { exampleRow, exampleStack } from "./styles";export default function ButtonBasic() { return ( <div className={exampleStack}> <div className={exampleRow}> <ElButton>Default</ElButton> <ElButton type="primary">Primary</ElButton> <ElButton type="success">Success</ElButton> <ElButton type="info">Info</ElButton> <ElButton type="warning">Warning</ElButton> <ElButton type="danger">Danger</ElButton> </div> <div className={exampleRow}> <ElButton plain>Plain</ElButton> <ElButton type="primary" plain>Primary</ElButton> <ElButton type="success" plain>Success</ElButton> <ElButton type="info" plain>Info</ElButton> <ElButton type="warning" plain>Warning</ElButton> <ElButton type="danger" plain>Danger</ElButton> </div> <div className={exampleRow}> <ElButton round>Round</ElButton> <ElButton type="primary" round>Primary</ElButton> <ElButton type="success" round>Success</ElButton> <ElButton type="info" round>Info</ElButton> <ElButton type="warning" round>Warning</ElButton> <ElButton type="danger" round>Danger</ElButton> </div> <div className={exampleRow}> <ElButton dashed>Dashed</ElButton> <ElButton type="primary" dashed>Primary</ElButton> <ElButton type="success" dashed>Success</ElButton> <ElButton type="info" dashed>Info</ElButton> <ElButton type="warning" dashed>Warning</ElButton> <ElButton type="danger" dashed>Danger</ElButton> </div> <div className={exampleRow}> <ElButton icon={<Search />} circle aria-label="search" /> <ElButton type="primary" icon={<Edit />} circle aria-label="edit" /> <ElButton type="success" icon={<Check />} circle aria-label="check" /> <ElButton type="info" icon={<Message />} circle aria-label="message" /> <ElButton type="warning" icon={<Star />} circle aria-label="star" /> <ElButton type="danger" icon={<Delete />} circle aria-label="delete" /> </div> </div> );}
禁用状态
你可以使用 disabled 属性来定义按钮是否被禁用。
使用 disabled 属性来控制按钮是否为禁用状态。该属性接受一个 Boolean 类型的值。
"use client";import { ElButton } from "@/components/element-plus/button";import { exampleRow, exampleStack } from "./styles";export default function ButtonDisabled() { return ( <div className={exampleStack}> <div className={exampleRow}> <ElButton disabled>Default</ElButton> <ElButton type="primary" disabled>Primary</ElButton> <ElButton type="success" disabled>Success</ElButton> <ElButton type="info" disabled>Info</ElButton> <ElButton type="warning" disabled>Warning</ElButton> <ElButton type="danger" disabled>Danger</ElButton> </div> <div className={exampleRow}> <ElButton plain disabled>Plain</ElButton> <ElButton type="primary" plain disabled>Primary</ElButton> <ElButton type="success" plain disabled>Success</ElButton> <ElButton type="info" plain disabled>Info</ElButton> <ElButton type="warning" plain disabled>Warning</ElButton> <ElButton type="danger" plain disabled>Danger</ElButton> </div> </div> );}
链接按钮
type="text" 已被 废弃，将于版本 3.0.0 时 移除，请考虑切换至新的 API。
新的 API link 于 2.2.1 版本时添加，你可以使用 type API 设置链接按钮的主题样式
Basic link button
Disabled link button
"use client";import { ElButton } from "@/components/element-plus/button";import styles from "./button.module.css";import { mb16 } from "./styles";export default function ButtonLink() { return ( <> <p className={styles.demoP}>Basic link button</p> <div className={mb16}> <ElButton link>plain</ElButton> <ElButton type="primary" link>primary</ElButton> <ElButton type="success" link>success</ElButton> <ElButton type="info" link>info</ElButton> <ElButton type="warning" link>warning</ElButton> <ElButton type="danger" link>danger</ElButton> </div> <p className={styles.demoP}>Disabled link button</p> <div> <ElButton link disabled>plain</ElButton> <ElButton type="primary" link disabled>primary</ElButton> <ElButton type="success" link disabled>success</ElButton> <ElButton type="info" link disabled>info</ElButton> <ElButton type="warning" link disabled>warning</ElButton> <ElButton type="danger" link disabled>danger</ElButton> </div> </> );}
文字按钮
文字按钮在现在有了全新的设计样式。 2.2.0 如果您想要使用老版样式的按钮，可以考虑使用 Link 组件。
API 也已更新，由于 type 属性会同时控制按钮的样式，因此我们通过一个新的 API text: boolean 来控制文字按钮。
没有边框和背景色的按钮。
Basic text button
Background color always on
Disabled text button
"use client";import { ElButton } from "@/components/element-plus/button";import styles from "./button.module.css";import { mb16 } from "./styles";export default function ButtonText() { return ( <> <p className={styles.demoP}>Basic text button</p> <div className={mb16}> <ElButton text>plain</ElButton> <ElButton type="primary" text>primary</ElButton> <ElButton type="success" text>success</ElButton> <ElButton type="info" text>info</ElButton> <ElButton type="warning" text>warning</ElButton> <ElButton type="danger" text>danger</ElButton> </div> <p className={styles.demoP}>Background color always on</p> <div className={mb16}> <ElButton text bg>plain</ElButton> <ElButton type="primary" text bg>primary</ElButton> <ElButton type="success" text bg>success</ElButton> <ElButton type="info" text bg>info</ElButton> <ElButton type="warning" text bg>warning</ElButton> <ElButton type="danger" text bg>danger</ElButton> </div> <p className={styles.demoP}>Disabled text button</p> <div> <ElButton text disabled>plain</ElButton> <ElButton type="primary" text disabled>primary</ElButton> <ElButton type="success" text disabled>success</ElButton> <ElButton type="info" text disabled>info</ElButton> <ElButton type="warning" text disabled>warning</ElButton> <ElButton type="danger" text disabled>danger</ElButton> </div> </> );}
图标按钮
使用图标为按钮添加更多的含义。你也可以单独使用图标不添加文字来节省显示区域占用。
使用 icon 属性来为按钮添加图标。您可以在我们的 Icon 组件中找到所需图标。通过向右方添加 <i> 标签来添加图标，你也可以使用自定义图标。
"use client";import { ElButton } from "@/components/element-plus/button";import { Delete, Edit, Search, Share, Upload } from "@/components/element-plus/generated/icons";import { ElIcon } from "@/components/element-plus/icon/ElIcon";export default function ButtonIcon() { return ( <div> <ElButton type="primary" icon={<Edit />} aria-label="edit" /> <ElButton type="primary" icon={<Share />} aria-label="share" /> <ElButton type="primary" icon={<Delete />} aria-label="delete" /> <ElButton type="primary" icon={<Search />}> Search </ElButton> <ElButton type="primary"> Upload <ElIcon className="el-icon--right"> <Upload /> </ElIcon> </ElButton> </div> );}
按钮组
以按钮组的方式出现，常用于多项类似操作。
在 2.11.9 中，您可以使用 direction 属性。
使用 <el-button-group> 对多个按钮分组。
"use client";import { useState } from "react";import { ElButton, ElButtonGroup } from "@/components/element-plus/button";import { ArrowLeft, ArrowRight, House, Notification, Operation,} from "@/components/element-plus/generated/icons";import { ElIcon } from "@/components/element-plus/icon/ElIcon";import { ElRadio, ElRadioGroup } from "@/components/element-plus/radio";import { mb16, mb8 } from "./styles";export default function ButtonGroupDemo() { const [direction, setDirection] = useState<"horizontal" | "vertical">( "horizontal", ); return ( <> <ElButtonGroup className={mb16}> <ElButton type="primary" icon={<ArrowLeft />}> Previous Page </ElButton> <ElButton type="primary"> Next Page <ElIcon className="el-icon--right"> <ArrowRight /> </ElIcon> </ElButton> </ElButtonGroup> <br /> <ElRadioGroup value={direction} onChange={(value) => setDirection(value as "horizontal" | "vertical")} className={mb8} > <ElRadio value="horizontal" label="Horizontal" /> <ElRadio value="vertical" label="Vertical" /> </ElRadioGroup> <br /> <ElButtonGroup direction={direction}> <ElButton type="primary" icon={<House />} aria-label="house" /> <ElButton type="primary" icon={<Operation />} aria-label="operation" /> <ElButton type="primary" icon={<Notification />} aria-label="notification" /> </ElButtonGroup> </> );}
加载状态按钮
点击按钮来加载数据，并向用户反馈加载状态。
通过设置 loading 属性为 true 来显示加载中状态。
您可以使用 loading 插槽或 loadingIcon 属性自定义您的 loading 图标。
ps: loading 插槽优先级高于 loadingIcon 属性
"use client";import { ElButton } from "@/components/element-plus/button";import { ElIcon } from "@/components/element-plus/icon/ElIcon";import { Eleme } from "@/components/element-plus/generated/icons";function CustomLoading() { return ( <span className="docs-custom-loading"> <svg className="docs-custom-loading__circular" viewBox="-10 -10 50 50"> <path className="docs-custom-loading__path" d="M 30 15 L 28 17 M 25.61 25.61 A 15 15, 0, 0, 1, 15 30 A 15 15, 0, 1, 1, 27.99 7.5 L 15 15" style={{ strokeWidth: 4, fill: "rgba(0, 0, 0, 0)" }} /> </svg> </span> );}export default function ButtonLoading() { return ( <> <ElButton type="primary" loading>Loading</ElButton> <ElButton type="primary" loadingIcon={<ElIcon className="is-loading"><Eleme /></ElIcon>} loading> Loading </ElButton> <ElButton type="primary" loadingIcon={<CustomLoading />} loading> Loading </ElButton> </> );}
调整尺寸
除了默认的大小，按钮组件还提供了几种额外的尺寸可供选择，以便适配不同的场景。
使用 size 属性额外配置尺寸，可使用 large 和 small 两种值。
"use client";import { ElButton } from "@/components/element-plus/button";import { Search } from "@/components/element-plus/generated/icons";import { flexRow, flexRowLast } from "./styles";export default function ButtonSize() { return ( <> <div className={flexRow}> <ElButton size="large">Large</ElButton> <ElButton>Default</ElButton> <ElButton size="small">Small</ElButton> <ElButton size="large" icon={<Search />}> Search </ElButton> <ElButton icon={<Search />}>Search</ElButton> <ElButton size="small" icon={<Search />}> Search </ElButton> </div> <div className={flexRow}> <ElButton size="large" round>Large</ElButton> <ElButton round>Default</ElButton> <ElButton size="small" round>Small</ElButton> <ElButton size="large" icon={<Search />} round> Search </ElButton> <ElButton icon={<Search />} round> Search </ElButton> <ElButton size="small" icon={<Search />} round> Search </ElButton> </div> <div className={flexRowLast}> <ElButton icon={<Search />} size="large" circle aria-label="search" /> <ElButton icon={<Search />} circle aria-label="search" /> <ElButton icon={<Search />} size="small" circle aria-label="search" /> </div> </> );}
Tag 2.3.4
您可以自定义元素标签。例如，按钮，div，路由链接，nuxt链接。
"use client";import { ElButton } from "@/components/element-plus/button";export default function ButtonTag() { return ( <> <ElButton>button</ElButton> <ElButton tag="div" role="button" tabIndex={0}>div</ElButton> <ElButton type="primary" tag="a" href="https://github.com/element-plus/element-plus" target="_blank" rel="noopener noreferrer" > a </ElButton> </> );}
自定义颜色 beta
您可以自定义按钮的颜色。
我们将自动计算按钮处于 hover 和 active 状态时的颜色。
自 2.13.7 起，color 属性也适用于 link 和 text 按钮。
"use client";import { ElButton } from "@/components/element-plus/button";const COLOR = "#626aef";export default function ButtonCustom() { return ( <div> <ElButton color={COLOR}>Default</ElButton> <ElButton color={COLOR} plain>Plain</ElButton> <ElButton color={COLOR} link>Link</ElButton> <ElButton color={COLOR} text>Text</ElButton> <ElButton color={COLOR} text bg>Text BG</ElButton> <ElButton color={COLOR} disabled>Disabled</ElButton> <ElButton color={COLOR} disabled plain>Disabled Plain</ElButton> <ElButton color={COLOR} disabled link>Disabled Link</ElButton> <ElButton color={COLOR} disabled text>Disabled Text</ElButton> <ElButton color={COLOR} disabled text bg>Disabled Text BG</ElButton> </div> );}
| 属性名 | 说明 | 类型 | 默认值 |
|---|
| size | 尺寸 | enum | — |
| type | 按钮类型，在设置 color 时，后者优先。 | enum | — |
| plain | 是否为朴素按钮 | boolean | false |
| text 2.2.0 | 是否为文字按钮 | boolean | false |
| bg 2.2.0 | 是否显示文字按钮背景颜色 | boolean | false |
| link 2.2.1 | 是否为链接按钮 | boolean | false |
| round | 是否为圆角按钮 | boolean | false |
| circle | 是否为圆形按钮 | boolean | false |
| dashed 2.13.3 | 是否是虚线按钮 | boolean | false |
| loading | 是否为加载中状态 | boolean | false |
| loading-icon | 自定义加载中状态图标组件 | string / Component | Loading |
| disabled | 按钮是否为禁用状态 | boolean | false |
| icon | 图标组件 | string / Component | — |
| autofocus | 原生 autofocus 属性 | boolean | false |
| native-type | 原生 type 属性 | enum | button |
| auto-insert-space | 两个中文字符之间自动插入空格(仅当文本长度为 2 且所有字符均为中文时才生效) | boolean | false |
| color | 自定义按钮颜色, 并自动计算 hover 和 active 触发后的颜色 | string | — |
| dark | dark 模式, 意味着自动设置 color 为 dark 模式的颜色 | boolean | false |
| tag 2.3.4 | 自定义元素标签 | string / Component | button |
| 事件名 | 说明 | 参数 |
|---|
| onClick | 点击按钮时触发；禁用或加载中时不会触发 | Function |
| 插槽名 | 说明 | React 写法 |
|---|
| default | 自定义默认内容 | children |
| loading | 自定义加载中组件 | loadingIcon |
| icon | 自定义图标组件 | icon |
| 名称 | 说明 | 类型 |
|---|
| ref | 按钮 html 元素 | object |
| size | 按钮尺寸 | object |
| type | 按钮类型 | object |
| disabled | 按钮禁用状态 | object |
| shouldAddSpace | 是否添加空格 | object |
| 属性名 | 说明 | 类型 | 默认值 |
|---|
| size | 控制组内按钮的尺寸 | enum | — |
| type | 控制组内按钮的类型 | enum | — |
| direction 2.11.9 | 显示方向 | enum | horizontal |
| 插槽名 | 说明 | 子标签 |
|---|
| default | 自定义按钮组内容 | Button |
