Toggle

Toggle is used to switch between two states. It supports standard switches, icon toggles, and button forms.

Basic Usage

Basic switch usage supporting two appearances: Rect and Round.

vue

<script setup>
import { ref } from 'vue'

const valueRect = ref(true)
const valueRound = ref(false)
</script>

<template>
  <div class="demo-box">
    <TuiToggle v-model="valueRect" />
    
    <TuiToggle v-model="valueRound" appearance="toggleRound" />
  </div>
</template>

Text Description

Set the text descriptions for the switch using activeText and inactiveText. Combined with the inlinePrompt attribute, the text can be displayed inside the switch.

Tip: When using inlinePrompt, it is recommended to set an appropriate width to accommodate the text.

vue

<script setup>
import { reactive, ref } from 'vue'

const state = reactive({
  val1: true,
  val2: false
})
</script>

<template>
  <TuiToggle 
    v-model="state.val1" 
    activeText="ON" 
    inactiveText="OFF" 
  />

  <TuiToggle 
    v-model="state.val2" 
    inlinePrompt 
    :width="70"
    activeText="ON" 
    inactiveText="OFF"
    appearance="toggleRect"
  />
  
  <TuiToggle 
    v-model="state.val1" 
    inlinePrompt 
    :width="100"
    activeText="Enabled" 
    inactiveText="Disabled"
  />
</template>

Icon Interaction Mode

The power of TuiToggle lies in the fact that it is more than just a switch; it can be transformed into a pure icon toggle or an icon button via the appearance property.

By passing an array ['inactiveIcon', 'activeIcon'] to the icon property, you can implement icon switching.

vue

<script setup>
import { ref } from 'vue'
const active = ref(false)
</script>

<template>
  <div class="icon-demo">
    <TuiToggle 
      v-model="active" 
      appearance="icon" 
      :icon="['tui-icon ti-lock', 'tui-icon ti-lock-open']" 
    />

    <TuiToggle 
      v-model="active" 
      appearance="iconPlain" 
      :icon="['tui-icon ti-view-expand', 'tui-icon ti-view-restore']" 
    />
  </div>
</template>

Button Form

By setting appearance to iconButton, the component will be rendered in a button style, commonly used for toolbars or panel controls.

vue

<script setup>
import { ref } from 'vue'
const stared = ref(false)
const locked = ref(true)
</script>

<template>
  <TuiToggle 
    v-model="stared" 
    appearance="iconButton" 
    size="large"
    :icon="['tui-icon ti-star', 'tui-icon tis-star']" 
  />

  <TuiToggle 
    v-model="locked" 
    appearance="iconButton" 
    activeText="Enabled"
    inactiveText="Disabled"
    icon="tui-icon ti-lock" 
  />
</template>

Sizes

Supports three sizes: large, default, and small, suitable for different layout scenarios.

vue

<script setup>
import { ref } from 'vue'
const val = ref(true)
</script>

<template>
  <TuiToggle v-model="val" size="large" />
  <TuiToggle v-model="val" size="default" />
  <TuiToggle v-model="val" size="small" />
  
  <TuiToggle v-model="val" appearance="iconButton" icon="tui-icon ti-home" size="large" />
  <TuiToggle v-model="val" appearance="iconButton" icon="tui-icon ti-home" size="small" />
</template>

Custom Colors

You can customize the background and border colors of the switch in different states by overriding CSS variables.

vue

<script setup>
import { ref } from 'vue'
const val = ref(true)
</script>

<template>
  <TuiToggle v-model="val" class="custom-status-toggle" inlinePrompt activeText="Online" />
</template>

<style scoped>
.custom-status-toggle {
  /* Define default state (Off) */
  --tui-tgl-bg_def: #909399;
  --tui-tgl-bd_def: #909399;

  /* Define active state (On) - e.g., change to green */
  --tui-tgl-bg_act: #67c23a;
  --tui-tgl-bd_act: #67c23a;
  
  /* Define Hover state */
  --tui-tgl-bg_hov: #a6a9ad;
}
</style>

API Reference

Props

Property	Description	Type	Default
modelValue	(v-model) Binding value	`Boolean`	Required
appearance	Appearance type, optional values: `'toggleRect'`, `'toggleRound'`, `'icon'`, `'iconPlain'`, `'iconButton'`	`String`	`'toggleRect'`
size	Size, optional values: `'large'`, `'default'`, `'small'`	`String`	`'default'`
activeText	Text description when the switch is ON	`String`	—
inactiveText	Text description when the switch is OFF	`String`	—
inlinePrompt	Whether icons or text are displayed inside the switch (Only valid for Rect/Round)	`Boolean`	`false`
width	The width of the switch (pixels)	`Number`	—
icon	Icon configuration. A string represents a single icon; an array `[inactive, active]` represents double icon switching	`String` / `Array`	`['tui-icon ti-toggle-off', 'tui-icon ti-toggle-on']`
disabled	Whether it is disabled	`Boolean`	`false`

Emits

Event Name	Description	Callback Parameters
update:modelValue	Triggered when the binding value changes	`value: boolean`
change	Callback when the switch state changes	`value: boolean`

Control Panel Toggle

TuiToggleControlPanel is a business component based on TuiToggle, specifically designed to control the visibility of global setting panels. It features a preset standard gear icon and encapsulates the logic bound to the control panel state, supporting flexible layouts and appearance configurations.

Basic Usage

By default, it is displayed as a plain gear icon (iconPlain). You can configure it as a button style or add text labels.

vue

<script setup>
import { ref } from 'vue'

const showPanel = ref(false)
</script>

<template>
  <div class="demo-gap">
    <TuiToggleControlPanel v-model="showPanel" />

    <TuiToggleControlPanel 
      v-model="showPanel" 
      appearance="iconButton" 
    />
    
    <TuiToggleControlPanel 
      v-model="showPanel" 
      appearance="icon" 
      size="large"
    />
  </div>
</template>

Labels and Layout

Display text via the showLabel attribute, and control the text's position relative to the icon (horizontal or vertical) using the direction attribute.

vue

<script setup>
import { ref } from 'ref'
const showPanel = ref(false)
</script>

<template>
  <div class="demo-gap">
    <TuiToggleControlPanel 
      v-model="showPanel" 
      showLabel 
      label="System Settings" 
    />

    <TuiToggleControlPanel 
      v-model="showPanel" 
      showLabel 
      direction="v" 
      label="Settings" 
    />
    
    <TuiToggleControlPanel 
      v-model="showPanel" 
      appearance="toggleRound" 
      showLabel 
      label="Control Panel"
    />
  </div>
</template>

API Reference

Property	Description	Type	Default
modelValue	(v-model) Binds the panel display state	`Boolean`	`false`
appearance	Appearance type, supports `iconPlain`, `iconButton`, `icon`, `toggleRound`, `toggleRect`	`String`	`'iconPlain'`
size	Size, optional `default`, `small`, `large`	`String`	`'default'`
icon	Custom icon	`String` / `Array`	`'tui-icon ti-cog'`
showLabel	Whether to display the text label	`Boolean`	`false`
label	Content of the text label	`String`	`null`
direction	Arrangement direction of icon and label, optional `'h'` (horizontal), `'v'` (vertical)	`String`	`'h'`

3D Panel Toggle

TuiToggleT3DPanel is based on TuiToggle and is specifically used to control the opening and closing of the Tui3DPanel component. It defaults to a dual-icon switching mechanism (2D Grid / 3D Cube) to intuitively display the current view mode.

Basic Usage

Displayed in icon toggle mode by default. Click to switch between 2D and 3D icons.

vue

<script setup>
import { ref } from 'vue'

const is3D = ref(false)
</script>

<template>
  <div class="demo-gap">
    <TuiToggleT3DPanel v-model="is3D" />

    <TuiToggleT3DPanel 
      v-model="is3D" 
      appearance="iconButton" 
      size="large" 
    />
  </div>
</template>

Custom Icons and Labels

You can override the default icon set or add auxiliary descriptive text.

vue

<script setup>
import { ref } from 'vue'
const is3D = ref(false)
</script>

<template>
  <div class="demo-gap">
    <TuiToggleT3DPanel 
      v-model="is3D" 
      :icon="['tui-icon ti-tablet', 'tui-icon ti-3d']" 
    />

    <TuiToggleT3DPanel 
      v-model="is3D" 
      showLabel 
      label="3D View" 
    />
    
    <TuiToggleT3DPanel 
      v-model="is3D" 
      showLabel 
      direction="v"
      label="View Mode" 
    />
  </div>
</template>

API Reference

Property	Description	Type	Default
modelValue	(v-model) Binds the 3D panel state	`Boolean`	`false`
appearance	Appearance type, supports `iconPlain`, `iconButton`, `icon`, `toggleRound`, `toggleRect`	`String`	`'iconPlain'`
size	Size, optional `default`, `small`, `large`	`String`	`'default'`
icon	Icon configuration, usually passed as an array `[inactive, active]`	`String` / `Array`	`['tui-icon ti-grid', 'tui-icon ti-cube']`
showLabel	Whether to display the text label	`Boolean`	`false`
label	Content of the text label	`String`	`null`
direction	Arrangement direction of icon and label, optional `'h'` (horizontal), `'v'` (vertical)	`String`	`'h'`

Toggle ​

Basic Usage ​

Text Description ​

Icon Interaction Mode ​

Button Form ​

Sizes ​

Custom Colors ​

API Reference ​

Props ​

Emits ​

Control Panel Toggle ​

Basic Usage ​

Labels and Layout ​

API Reference ​

3D Panel Toggle ​

Basic Usage ​

Custom Icons and Labels ​

API Reference ​

Toggle

Basic Usage

Text Description

Icon Interaction Mode

Button Form

Sizes

Custom Colors

API Reference

Props

Emits

Control Panel Toggle

Basic Usage

Labels and Layout

API Reference

3D Panel Toggle

Basic Usage

Custom Icons and Labels

API Reference