2021-10-22 19:32:39 +08:00
---
2021-10-25 15:21:08 +08:00
title: Switch
2021-10-22 19:32:39 +08:00
lang: en-US
---
2021-09-17 00:18:50 +08:00
# Switch
2020-08-13 15:18:26 +08:00
Switch is used for switching between two opposing states.
2021-09-17 00:18:50 +08:00
## Basic usage
2021-04-26 11:53:09 +08:00
2020-08-13 15:18:26 +08:00
:::demo Bind `v-model` to a `Boolean` typed variable. The `active-color` and `inactive-color` attribute decides the background color in two states.
2021-09-17 00:18:50 +08:00
switch/basic
2021-04-26 11:53:09 +08:00
2020-08-13 15:18:26 +08:00
:::
2021-09-17 00:18:50 +08:00
## Text description
2021-04-26 11:53:09 +08:00
2021-10-30 21:23:29 +08:00
You can add `active-text` and `inactive-text` attribute to show texts. use `inline-prompt` attribute to control text is displayed inside dot.
2020-08-13 15:18:26 +08:00
:::demo You can add `active-text` and `inactive-text` attribute to show texts.
2021-09-17 00:18:50 +08:00
switch/text-description
2021-04-26 11:53:09 +08:00
2020-08-13 15:18:26 +08:00
:::
2021-10-27 23:17:13 +08:00
## Display custom icons
:::tip
Use the `active-icon` and `active-icon` attribute to add icon. You can pass either string for the component name (registered in advance) or the component itself which is a SVG Vue component. Element Plus has provided a set of icon that you can find at [icon ](/en-US/component/icon )
:::
2021-10-30 21:23:29 +08:00
:::demo You can add `active-icon` and `inactive-icon` attribute to show icons. use `inline-prompt` attribute to control icon is displayed inside dot.
2021-10-27 23:17:13 +08:00
switch/custom-icons
:::
2021-09-17 00:18:50 +08:00
## Extended value types
2020-08-13 15:18:26 +08:00
:::demo You can set `active-value` and `inactive-value` attributes. They both receive a `Boolean` , `String` or `Number` typed value.
2021-09-17 00:18:50 +08:00
switch/extended-value-types
2020-08-13 15:18:26 +08:00
:::
2021-09-17 00:18:50 +08:00
## Disabled
2020-08-13 15:18:26 +08:00
:::demo Adding the `disabled` attribute disables Switch.
2021-09-17 00:18:50 +08:00
switch/disabled
2021-04-26 11:53:09 +08:00
2020-08-13 15:18:26 +08:00
:::
2021-09-17 00:18:50 +08:00
## Loading
2020-11-11 18:19:52 +08:00
:::demo Setting the `loading` attribute to `true` indicates a loading state on the Switch.
2021-09-17 00:18:50 +08:00
switch/loading
2021-04-26 11:53:09 +08:00
:::
2021-09-17 00:18:50 +08:00
## prevent switching
2021-04-26 11:53:09 +08:00
2021-09-12 18:02:52 +08:00
:::demo set the `before-change` property, If `false` is returned or a `Promise` is returned and then is rejected, will stop switching.
2021-04-26 11:53:09 +08:00
2021-09-17 00:18:50 +08:00
switch/prevent-switching
2021-04-26 11:53:09 +08:00
2020-11-11 18:19:52 +08:00
:::
2021-09-17 00:18:50 +08:00
## Attributes
2020-08-13 15:18:26 +08:00
2021-09-04 19:29:28 +08:00
| Attribute | Description | Type | Accepted Values | Default |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | --------------- | ------- |
| model-value / v-model | binding value, it should be equivalent to either `active-value` or `inactive-value` , by default it's `boolean` type | boolean / string / number | — | — |
| disabled | whether Switch is disabled | boolean | — | false |
| loading | whether Switch is in loading state | boolean | — | false |
| width | width of Switch | number | — | 40 |
2021-11-11 11:40:22 +08:00
| inline-prompt | whether icon or text is displayed inside dot, only the first character will be rendered for text | boolean | — | false |
2021-10-27 23:17:13 +08:00
| active-icon | component of the icon displayed when in `on` state, overrides `active-text` | string / Component | — | — |
| inactive-icon | component of the icon displayed when in `off` state, overrides `inactive-text` | string / Component | — | — |
2021-09-04 19:29:28 +08:00
| active-text | text displayed when in `on` state | string | — | — |
| inactive-text | text displayed when in `off` state | string | — | — |
| active-value | switch value when in `on` state | boolean / string / number | — | true |
| inactive-value | switch value when in `off` state | boolean / string / number | — | false |
| active-color | background color when in `on` state | string | — | #409EFF |
| inactive-color | background color when in `off` state | string | — | #C0CCDA |
| border-color | border color of the switch | string | — | — |
| name | input name of Switch | string | — | — |
| validate-event | whether to trigger form validation | boolean | — | true |
| before-change | before-change hook before the switch state changes. If `false` is returned or a `Promise` is returned and then is rejected, will stop switching | function | — | — |
2020-08-13 15:18:26 +08:00
2021-09-17 00:18:50 +08:00
## Events
2020-08-13 15:18:26 +08:00
2021-04-26 11:53:09 +08:00
| Event Name | Description | Parameters |
| ---------- | --------------------------- | -------------------- |
| change | triggers when value changes | value after changing |
2020-08-13 15:18:26 +08:00
2021-09-17 00:18:50 +08:00
## Methods
2021-04-26 11:53:09 +08:00
| Method | Description | Parameters |
| ------ | -------------------------- | ---------- |
| focus | focus the Switch component | — |
