Icon Button

개요

아이콘 버튼은 아이콘만으로 빠른 단일 액션을 실행하는 컴포넌트 입니다.

공간을 아끼면서 잦은 단일 액션을 노출해야 할 때
예) 즐겨찾기, 좋아요, 북마크, 공유, 더보기(⋯), 행/카드 툴바 액션
텍스트 버튼보다 즉시 인지와 반복 사용이 중요한 경우
토글 상태(켜짐/꺼짐)를 시각적으로 전환해야 할 때 (selected)

이렇게 활용하세요

✅ 권장 사용 방식

단일 액션: 즐겨찾기, 좋아요, 북마크, 고정(핀), 공유, 더보기(⋯)
토글형 상태 표시: Selected 스타일과 aria-pressed로 ON/OFF를 즉시 구분

❌ 비권장 사례

시각 정보 영역: 의미가 모호한 아이콘(특히 모바일) → 라벨/툴팁 없으면 사용 금지. 일회성 실행에 Selected 토글 사용(상태 오해 유발)
네비게이션: 페이지 이동/내비게이션 용도 사용 → 링크/탭으로 대체
파괴적 액션: 파괴적 액션을 라벨 없이 단독 아이콘으로 노출하는 경우(삭제 등) → Danger + 확인 단계 또는 텍스트 버튼

Variants

Impact
Top Tier

Impact는 사용자의 즉각적인 주목과 행동을 유도하기 위한 최대 강조 톤입니다. 기존 Primary보다 한 단계 높은 우선순위로, 한 화면(또는 툴바)에는 1개만 사용합니다. 파괴적 행위(삭제 등)에는 사용하지 않습니다.

Inactive

Hover

Pressed

Disabled

<IconButton variant="contained" color="impact" size="xLarge">
  <StarFill />
</IconButton>
<IconButton variant="contained" color="impact" size="xLarge" disabled>
  <StarFill />
</IconButton>
<IconButton variant="contained" color="impact" size="xLarge" loading>
  <StarFill />
</IconButton>

Primary
1순위 위계

가장 많이 쓰는 기본 강조 아이콘 버튼입니다. 배경과의 대비가 애매한 곳에서도 인지가 안정적입니다. 여러 개 나열될 경우엔 Outlined/Text로 시각 무게를 조절해야합니다.

Inactive

Hover

Pressed

Disabled

<IconButton variant="contained" color="primary" size="xLarge">
  <StarFill />
</IconButton>
<IconButton variant="contained" color="primary" size="xLarge" disabled>
  <StarFill />
</IconButton>
<IconButton variant="contained" color="primary" size="xLarge" loading>
  <StarFill />
</IconButton>

Outlined
2순위 위계

배경 채움 없이 보더만 있는 2순위 위계의 기본 버튼입니다. 여러 아이콘이 나란한 툴바나 카드/테이블 헤더에 유리합니다.

Inactive

Hover

Pressed

Disabled

<IconButton variant="outlined" color="primary" size="xLarge">
  <StarFill />
</IconButton>
<IconButton variant="outlined" color="primary" size="xLarge" disabled>
  <StarFill />
</IconButton>
<IconButton variant="outlined" color="primary" size="xLarge" loading>
  <StarFill />
</IconButton>

Text
3순위 위계

채움/보더 없이 아이콘만 보이는 가장 가벼운 형태입니다. 가벼운 액션, PC의 Hover + Tooltip 보강이 가능한 곳에 적합합니다. 복잡한 배경 위나 모바일 핵심 액션에는 지양합니다.

Inactive

Hover

Pressed

Disabled

<IconButton variant="text" color="primary" size="xLarge">
  <StarFill />
</IconButton>
<IconButton variant="text" color="primary" size="xLarge" disabled>
  <StarFill />
</IconButton>
<IconButton variant="text" color="primary" size="xLarge" loading>
  <StarFill />
</IconButton>

Selected
Positive Status

Primary와 동등하거나 더 높은 위계를 갖는 긍정형 CTA 버튼입니다. 조건 완료, 스위치 활성화 등 특정 상태에서 사용되며,텍스트나 아이콘과 함께 조합할 수 있습니다. Primary가 이미 존재할 경우, 차별화된 CTA가 필요할 때 활용됩니다.

Inactive

Hover

Pressed

Disabled

<IconButton variant="contained" color="success" size="xLarge">
  <StarFill />
</IconButton>
<IconButton variant="contained" color="success" size="xLarge" disabled>
  <StarFill />
</IconButton>
<IconButton variant="contained" color="success" size="xLarge" loading>
  <StarFill />
</IconButton>

Danger
Negative Status

복구 불가능한 작업이나 중대한 변화를 유도할 때,강력한 경고의 의미로 사용되는 버튼입니다. 파괴적인 결과가 없는 경우에는 사용을 지양합니다.

Inactive

Hover

Pressed

Disabled

<IconButton variant="contained" color="error" size="xLarge">
  <Close />
</IconButton>
<IconButton variant="contained" color="error" size="xLarge" disabled>
  <Close />
</IconButton>
<IconButton variant="contained" color="error" size="xLarge" loading>
  <Close />
</IconButton>

Sizes

아이콘 버튼은 사용 맥락에 따라 다섯 가지 사이즈로 제공됩니다. 터치 영역과 UI 밀도를 고려하여 선택하세요.

<IconButton size="xLarge"><StarFill /></IconButton>
<IconButton size="large"><StarFill /></IconButton>
<IconButton size="medium"><StarFill /></IconButton>
<IconButton size="small"><StarFill /></IconButton>
<IconButton size="xSmall"><StarFill /></IconButton>

Size Name	Use Case
xLarge (50px)	히어로/캔버스 상단의 핵심 도구(지도 확대·레이어, 미디어 컨트롤) 등 터치/접근성 우선 화면
large (42px)	상단 툴바의 주요 아이콘, 카드/섹션 헤더의 1차 액션
medium (36px)	일반 툴바·리스트/테이블 행 액션(즐겨찾기, 공유, 더보기)
small (32px)	조밀 레이아웃; 테이블 셀·카드 내부 보조 액션, 배지 동반
xSmall (28px)	PC 전용 초밀도; 데이터그리드 세부 제어(모바일 비권장)

Loading State

<IconButton loading><StarFill /></IconButton>
<IconButton variant="outlined" loading><StarFill /></IconButton>
<IconButton variant="contained" color="primary" loading><StarFill /></IconButton>

With Ref

ref를 사용하여 아이콘 버튼에 직접 접근할 수 있습니다.

import { useRef } from 'react';

function IconButtonWithRef() {
  const ref = useRef<HTMLButtonElement>(null);
  
  const handleClick = () => {
    console.log(ref.current);
  };
  
  return (
    <IconButton ref={ref} onClick={handleClick}>
      <StarFill />
    </IconButton>
  );
}

Props

Prop	Type	Default
`variant?`	`"text" \| "outlined" \| "contained"`	`"text"`
`color?`	`"impact" \| "primary" \| "secondary" \| "error" \| "success" \| "white"`	`"primary"`
`size?`	`"xLarge" \| "large" \| "medium" \| "small" \| "xSmall"`	`"medium"`
`disabled?`	`boolean`	`false`
`selected?`	`boolean`	`false`
`loading?`	`boolean`	`false`
`asChild?`	`boolean`	`false`

Icon Button

On this page