Radio 라디오 버튼

원문 보기 위키 갱신 2026.10.11

여러 선택지 가운데 딱 하나만 고를 때 사용하는 라디오 버튼 컴포넌트예요.

출처: 문서

본문

언제 사용하나요

사용자가 하나의 데이터 집합에서 단 하나의 옵션을 고르고, 선택 가능한 모든 옵션을 나란히 확인할 수 있어야 하며, 옵션 개수가 2~7개일 때 라디오 버튼을 사용하는 걸 추천해요.

서로 독립적인 단일 선택 항목

:::demo

<template>
  <d-radio v-for="item in baseList" v-model="baseChoose" :key="item" :value="item" class="mb-2">
    The Radio value is: {{ item }}
  </d-radio>
</template>

<script>
import { defineComponent, ref } from 'vue';

export default defineComponent({
  setup() {
    const baseList = ref(['Item1', 'Item2', 'Item3']);
    let baseChoose = ref('Item1');

    return {
      baseList,
      baseChoose,
    };
  },
});
</script>

:::

radio 조건에 따라 전환 동작 막기

조건을 판단해서 두 번째 항목으로는 전환하지 못하게 막는 예제예요.

:::demo

<template>
  <d-radio
    v-for="item in filterList"
    v-model="filterChoose"
    :key="item"
    :value="item"
    :beforeChange="filterBeforeChange"
    class="mb-2"
    @change="filterValChange"
  >
    The Radio value is: {{ item }}
  </d-radio>
</template>

<script>
import { defineComponent, ref } from 'vue';

export default defineComponent({
  setup() {
    const filterList = ref(['Item1', 'Item2', 'Item3']);
    let filterChoose = ref('Item1');

    return {
      filterList,
      filterChoose,
      filterBeforeChange(value) {
        return value !== 'Item2';
      },
      filterValChange(val) {
        console.log('current value', val);
      },
    };
  },
});
</script>

:::

radio-group 조건에 따라 전환 동작 막기

조건을 판단해서 두 번째 radio-group으로는 전환하지 못하게 막아요.

:::demo

<template>
  <d-radio-group class="mb-2" direction="row" v-model="groupFilterChoose1" :beforeChange="groupFilterBeforeChange">
    <d-radio v-for="item in groupFilterList1" :key="item" :value="item">
      {{ item }}
    </d-radio>
  </d-radio-group>
  <br />
  <d-radio-group v-model="groupFilterChoose2" direction="row" disabled>
    <d-radio v-for="item in groupFilterList2" :key="item" :value="item">
      {{ item }}
    </d-radio>
  </d-radio-group>
</template>

<script>
import { defineComponent, ref } from 'vue';

export default defineComponent({
  setup() {
    const groupFilterList1 = ref(['Spring', 'Summer', 'Autumn', 'Winter']);
    let groupFilterChoose1 = ref('Spring');

    const groupFilterList2 = ['Spring', 'Summer', 'Autumn', 'Winter'];
    const groupFilterChoose2 = ref('Summer');

    return {
      groupFilterList1,
      groupFilterChoose1,
      groupFilterList2,
      groupFilterChoose2,
      groupFilterBeforeChange(value) {
        return value !== 'Item2';
      },
    };
  },
});
</script>

:::

비활성화

:::demo

<template>
  <d-radio v-for="item in disabledList" v-model="disabledChoose" :key="item" :value="item" class="mb-2" disabled>
    The Radio value is: {{ item }}
  </d-radio>
</template>

<script>
import { defineComponent, ref } from 'vue';

export default defineComponent({
  setup() {
    const disabledList = ref(['Item1', 'Item2', 'Item3']);
    let disabledChoose = ref('Item1');

    return {
      disabledList,
      disabledChoose,
    };
  },
});
</script>

:::

가로 배치

:::demo

<template>
  <d-radio-group direction="row" v-model="directionRowChoose">
    <d-radio v-for="item in directionRowList" :key="item" :value="item"> The Radio value is: {{ item }}</d-radio>
  </d-radio-group>
</template>

<script>
import { defineComponent, ref } from 'vue';

export default defineComponent({
  setup() {
    const directionRowList = ref(['Item1', 'Item2', 'Item3']);
    let directionRowChoose = ref('Item1');

    return {
      directionRowList,
      directionRowChoose,
    };
  },
});
</script>

:::

세로 배치

:::demo

<template>
  <d-radio-group :values="directionColumnList" v-model="directionColumnChoose"></d-radio-group>
</template>

<script>
import { defineComponent, ref } from 'vue';

export default defineComponent({
  setup() {
    const directionColumnList = ['Spring', 'Summer', 'Autumn', 'Winter'];
    const directionColumnChoose = ref('Summer');

    return {
      directionColumnList,
      directionColumnChoose,
    };
  },
});
</script>

:::

커스텀 라디오 항목

데이터 소스는 일반 배열, 객체 배열 등으로 만들 수 있어요.

:::demo

<template>
  <d-radio-group direction="row" v-model="customChoose1">
    <d-radio v-for="item in customList1" :key="item" :value="item"> The Radio value is: {{ item }}</d-radio>
  </d-radio-group>
  <d-radio-group direction="row" v-model="customChoose2">
    <d-radio v-for="item in customList2" :key="item.name" :value="item.name"> The Radio value is: {{ item.name }}
    </d-radio>
  </d-radio-group>
</template>

<script>
import { defineComponent, ref } from 'vue';

export default defineComponent({
  setup() {
    const customList1 = ref(['Item1', 'Item2', 'Item3']);
    let customChoose1 = ref('Item1');

    const customList2 = [{ name: 'Item1' }, { name: 'Item2' }, { name: 'Item3' }];
    let customChoose2 = ref('Item3');

    return {
      customList1,
      customChoose1,
      customList2,
      customChoose2,
    };
  },
});
</script>

:::

크기와 테두리

:::demo

<template>
  <h4>Small</h4>
  <d-radio-group
    :values="sizeBorderList"
    v-model="sizeBorderChoose3"
    size="sm"
    border
    direction="row"
    style="margin-bottom: 10px;"
  ></d-radio-group>

  <h4>Middle</h4>
  <d-radio-group
    :values="sizeBorderList"
    v-model="sizeBorderChoose2"
    size="md"
    border
    direction="row"
    style="margin-bottom: 10px;"
  ></d-radio-group>

  <h4>Large</h4>
  <d-radio-group
    :values="sizeBorderList"
    v-model="sizeBorderChoose1"
    size="lg"
    border
    direction="row"
    style="margin-bottom: 10px;"
  ></d-radio-group>
</template>

<script>
import { defineComponent, ref } from 'vue';

export default defineComponent({
  setup() {
    const sizeBorderList = ['Spring', 'Summer'];
    const sizeBorderChoose1 = ref('Spring');
    const sizeBorderChoose2 = ref('Spring');
    const sizeBorderChoose3 = ref('Spring');

    return {
      sizeBorderList,
      sizeBorderChoose1,
      sizeBorderChoose2,
      sizeBorderChoose3,
    };
  },
});
</script>

:::

버튼 형태

d-radio를 d-radio-button으로 바꿔주기만 하면 돼요. 데이터 소스는 일반 배열, 객체 배열 등으로 만들 수 있어요.

:::demo


<template>
  <h4>禁用</h4>
  <d-radio-group direction="row" v-model="buttonChoose1" size="sm" style="margin-bottom: 10px;">
    <d-radio-button v-for="item in buttonList1" :key="item.name" :value="item.name" :disabled="item.disabled"
    >{{ item.name }}
    </d-radio-button>
  </d-radio-group>

  <h4>默认</h4>
  <d-radio-group direction="row" v-model="buttonChoose2" size="md" style="margin-bottom: 10px;">
    <d-radio-button v-for="item in buttonList2" :key="item.name" :value="item.name">{{ item.name }}</d-radio-button>
  </d-radio-group>

  <h4>自定义填充颜色、文字颜色</h4>
  <d-radio-group direction="row" v-model="buttonChoose3" size="lg" style="margin-bottom: 10px;" fill="rgb(255,193,7)"
                 text-color="#ca3d3d"
  >
    <d-radio-button v-for="item in buttonList3" :key="item" :value="item"> {{ item }}</d-radio-button>
  </d-radio-group>
</template>

<script>
import { defineComponent, ref } from 'vue';

export default defineComponent({
  setup() {
    const buttonList1 = [{
      name: 'Spring',
      disabled: true
    }, { name: 'Summer' }, { name: 'Autumn' }, { name: 'Winter' }];
    let buttonChoose1 = ref('Summer');
    
    const buttonList2 = [{ name: 'Spring' }, { name: 'Summer' }, { name: 'Autumn' }, { name: 'Winter' }];
    let buttonChoose2 = ref('Spring');

    const buttonList3 = ref(['Spring', 'Summer', 'Autumn', 'Winter']);
    let buttonChoose3 = ref('Spring');
    
    return {
      buttonList1,
      buttonChoose1,
      buttonList2,
      buttonChoose2,
      buttonList3,
      buttonChoose3,
    };
  },
});
</script>

:::

Radio 파라미터

파라미터	타입	기본값	설명	Demo 링크
v-model	`string \|number \| boolean`	--	바인딩 값	서로 독립적인 단일 옵션
value	`string \|number \| boolean`	--	필수, 라디오 항목 값	서로 독립적인 단일 옵션
name	`string`	--	선택, 라디오 항목 이름	서로 독립적인 단일 옵션
disabled	`boolean`	false	선택, 해당 라디오 항목 비활성화 여부	비활성화
before-change	`Function / Promise`	--	선택, radio 전환 전 콜백 함수. false를 반환하면 radio 전환을 막을 수 있음	콜백 전환
border	`boolean`	false	선택, 테두리 여부	테두리
size	IRadioSize	md	선택, radio 크기. border 속성이 있을 때만 유효	크기
can-cancel-select	`boolean`	false	선택, 선택 후 다시 클릭으로 선택 해제 가능 여부
show-glow-style	`boolean`	true	선택, 호버 발광 효과 표시 여부

Radio 이벤트

파라미터	타입	설명	Demo 링크
change	`EventEmitter<string>`	라디오 항목 값 변경 시 트리거. 선택된 값 반환	서로 독립적인 단일 옵션

RadioGroup 파라미터

파라미터	타입	기본값	설명	Demo 링크
v-model	`string \|number \| boolean`	--	바인딩 값	세로 배치
name	`string`	--	선택, 라디오 버튼 이름	세로 배치
values	`array`	--	선택, 라디오 데이터 그룹	세로 배치
disabled	`boolean`	false	선택, 해당 옵션 그룹 비활성화 여부	radio-group 조건부 전환 중단
direction	`'row'` \| `'column'`	'column'	선택, 가로 또는 세로 배치 설정	가로 배치
before-change	`Function` \| `Promise`	--	선택, radio-group 전환 전 콜백 함수. false를 반환하면 radio-group 전환을 막을 수 있음	콜백 전환
border	`boolean`	false	선택, 테두리 여부	테두리
size	IRadioSize	md	선택, radio 크기. border 속성이 있을 때만 유효	크기
fill	`string`	--	선택, 버튼 형태 Radio 활성화 시 채움색과 테두리색	버튼 형태
text-color	`string`	--	선택, 버튼 선택 시 폰트 스타일. 버튼 형태에서만 존재	버튼 형태

RadioGroup 이벤트

이벤트명	타입	설명	Demo 링크
change	`EventEmitter<string>`	라디오 항목 값 변경 시 트리거. 선택된 값 반환	세로 배치

RadioButton 파라미터

파라미터	타입	기본값	설명	Demo 링크
value	`string \|number \| boolean`	--	필수, 라디오 항목 값	버튼 형태
name	`string`	--	선택, 라디오 항목 이름	버튼 형태
disabled	`boolean`	false	선택, 해당 라디오 항목 비활성화 여부	버튼 형태

Radio 타입 정의

IRadioSize

type IRadioSize = 'lg' | 'md' | 'sm';

더 알아보기 (Learn more)

before-change 콜백으로 조건에 따라 전환을 막을 수 있고, d-radio-group으로 여러 라디오를 묶어 가로·세로 배치, 테두리, 버튼 형태까지 손쉽게 구성할 수 있어요. 파라미터와 타입 정의는 위 표를 참고하세요.