Radio

TuiRadio is used to select a single state from multiple options. It offers a high degree of customization, supporting various forms such as standard radio buttons, button groups, and card lists, with support for both horizontal and vertical layouts.

Basic Usage

Data-Driven Rendering (Options)

The simplest way to use it is by passing a configuration array through the options property.

• options: Array items must include label (display text) and value (bound value).

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

const value = ref(0);
const options = [
  { label: 'Option 1', value: 0 },
  { label: 'Option 2', value: 1 },
  { label: 'Disabled Item', value: 2, disabled: true }
];
</script>

<template>
  <TuiRadio v-model="value" :options="options" />
</template>

Slot Customization (Slot)

Using the <TuiRadioItem> sub-component allows for more complex layouts, such as embedding color blocks, icons, or complex HTML structures within the radio component.

<template>
  <TuiRadio v-model="color">
    <TuiRadioItem value="blue">
      <div style="width: 20px; height: 20px; background: blue;"></div>
    </TuiRadioItem>
    <TuiRadioItem value="red">
      <div style="width: 20px; height: 20px; background: red;"></div>
    </TuiRadioItem>
  </TuiRadio>
</template>

Custom Content (Color Picker Example)

By setting defaultIcon to false, you can hide the default radio circle and customize the rendering logic within <TuiRadioItem> using slots. Utilizing the .is-active state (automatically added by the component) allows for easy implementation of interactive effects like "checkmark appearing when selected."

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

const activeTheme = ref(0);

const themes = [
  { label: "LightBlue", colors: ['#409eff', '#ecf5ff'] },
  { label: "DarkMix", colors: ['#303133', '#909399'] },
  { label: "Forest", colors: ['#67c23a', '#e1f3d8'] },
];
</script>

<template>
  <TuiRadio v-model="activeTheme" :defaultIcon="false" class="theme-selector">
    <TuiRadioItem 
      v-for="(item, index) in themes" 
      :key="index" 
      :value="index" 
      class="theme-item"
    >
      <div class="color-view">
        <i class="tui-icon ti-check check-mark"></i>
        <div class="color-half" :style="{ backgroundColor: item.colors[0] }"></div>
        <div class="color-half" :style="{ backgroundColor: item.colors[1] }"></div>
      </div>
    </TuiRadioItem>
  </TuiRadio>
</template>

<style lang="less" scoped>
.theme-selector {
  .theme-item {
    margin-right: 12px;
    
    // TuiRadioItem automatically adds .is-active class when selected
    &.is-active {
      .check-mark { opacity: 1; transform: translate(-50%, -50%) scale(1); }
    }

    .color-view {
      position: relative;
      width: 40px;
      height: 40px;
      border-radius: 6px;
      overflow: hidden;
      cursor: pointer;
      box-shadow: 0 2px 4px rgba(0,0,0,0.1);
      
      .color-half {
        width: 100%;
        height: 50%;
      }

      .check-mark {
        position: absolute;
        left: 50%;
        top: 50%;
        transform: translate(-50%, -50%) scale(0.5);
        color: #fff;
        font-size: 20px;
        opacity: 0;
        transition: all 0.2s;
        text-shadow: 0 1px 2px rgba(0,0,0,0.2);
      }
    }
  }
}
</style>

Appearance Styles

Three primary styles can be toggled using the appearance property.

Simple Style (Simple) - Default

The standard radio button style with a circular selection indicator.

<TuiRadio appearance="simple" :options="options" />

Button Style (Button)

A solid button style where the background fills when selected, commonly used for toolbars or mode switching. Pair it with the separable property to control whether there is spacing between buttons.

<template>
  <TuiRadio appearance="button" :options="options" />
  
  <TuiRadio appearance="button" separable :options="options" />
</template>

Card Style (ButtonPlain)

An outlined card style. When selected, the border highlights and a light background appears, suitable for scenarios with fewer options but longer content.

<TuiRadio appearance="buttonPlain" :options="options" />

Layout and Direction

Vertical Arrangement

Set direction="v" to stack the options vertically.

<TuiRadio direction="v" :options="options" />

Text Direction (TextDirection)

Setting textDirection="v" allows the text within the options to be arranged vertically (top to bottom). This is useful for specific sidebar designs.

<TuiRadio direction="v" textDirection="v" :options="options" />

Icons and Decoration

Custom Icons

TuiRadio supports flexible icon configuration:

• defaultIcon: Whether to show the default circle/checkmark indicator (defaults to true).
• icon: Pass icons through option data or the component. You can pass an array ['unselected icon', 'selected icon'] to achieve a state-switching effect.

<script setup>
const iconOptions = [
  // Pass an array for icon switching: [unselected, selected]
  { label: 'Favorite', value: 1, icon: ['tui-icon ti-star', 'tui-icon tis-star'] },
  { label: 'File', value: 2, icon: 'tui-icon ti-file' }
];
</script>

<template>
  <TuiRadio 
    :defaultIcon="false" 
    appearance="buttonPlain" 
    :options="iconOptions" 
  />
</template>

Size

Supports three sizes: large, default, and small.

<TuiRadio size="small" :options="options" />
<TuiRadio size="default" :options="options" />
<TuiRadio size="large" :options="options" />

API Reference

TuiRadio Props

Property	Type	Default	Description
modelValue	String/Number/Boolean	-	Bound value.
options	Array	[]	Data source.
appearance	String	'simple'	Appearance style. Options: simple, button, buttonPlain.
direction	String	'h'	Arrangement direction. Options: h (horizontal), v (vertical).
size	String	'default'	Size. Options: large, default, small.
defaultIcon	Boolean	true	Whether to show the default radio indicator icon (circle/checkmark).
separable	Boolean	false	Whether to separate buttons (only valid in button/buttonPlain modes).
align	String	null	Internal content alignment. Options: start, center, end.
textDirection	String	null	Text arrangement direction. Options: h, v.
itemMaxWidth	Number/String	-	Maximum width of a single option.
disabled	Boolean	false	Whether to disable the entire component.
className	String	-	Custom class name.

TuiRadio Events

Event Name	Description	Callback Parameters
update:modelValue	Triggered when the bound value changes.	(value)
change	Triggered when the selected value changes.	(value)

TuiRadioItem Props

Property	Type	Default	Description
value	String/Number/Boolean	Required	The value of the option.
icon	String/Array	null	Icon. Can be a string or an [inactive, active] array.
disabled	Boolean	false	Whether to disable this option.