아이콘 버튼

아이콘 버튼 (Icon Button)

단일 아이콘과 함께 사용하도록 특별히 설계된 버튼이에요. button 요소 기반으로 만들어졌어요.

출처: 문서

본문

단일 아이콘과 함께 사용하도록 특별히 설계된 버튼이에요.

<IconButton>
  <MagnifyingGlassIcon width="18" height="18" />
</IconButton>

API Reference

이 컴포넌트는 button 요소를 기반으로 하며 공통 margin props를 지원해요.

Prop	Type	Default
`asChild`	`boolean`	No default value
`size`	`Responsive<"1" \| "2" \| "3" \| "4">`	`"2"`
`variant`	`enum`	`"solid"`
`color`	`enum`	No default value
`highContrast`	`boolean`	No default value
`radius`	`"none" \| "small" \| "medium" \| "large" \| "full"`	No default value
`loading`	`boolean`	`false`

예제 (Examples)

Icon Button 컴포넌트는 보이는 텍스트가 없으므로 aria-label 또는 aria-labelledby prop을 포함하는 것을 강력히 권장해요. 화면 리더는 이 label에 의존해서 버튼의 목적을 사용자에게 알려 주거든요.

Size

size prop으로 버튼의 크기를 제어해요.

<Flex align="center" gap="3">
  <IconButton size="1" variant="soft">
    <MagnifyingGlassIcon width="15" height="15" />
  </IconButton>

  <IconButton size="2" variant="soft">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>

  <IconButton size="3" variant="soft">
    <MagnifyingGlassIcon width="22" height="22" />
  </IconButton>
</Flex>

Variant

variant prop으로 버튼의 시각적 스타일을 제어해요.

<Flex gap="3">
  <IconButton variant="classic">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>

  <IconButton variant="solid">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>

  <IconButton variant="soft">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>

  <IconButton variant="surface">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>

  <IconButton variant="outline">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>
</Flex>

Ghost

ghost variant를 사용해 꾸밈(chrome) 없이 버튼을 표시해요. Ghost 버튼은 레이아웃에서 텍스트처럼 동작해요. 활성·호버 상태에서 패딩을 유지하면서 형제 요소와 시각적으로 정렬되도록 음수 마진을 사용하거든요.

<IconButton variant="ghost">
  <MagnifyingGlassIcon width="18" height="18" />
</IconButton>

Color

color prop으로 특정 color를 지정해요.

<Flex gap="3">
  <IconButton color="crimson" variant="soft">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>

  <IconButton color="indigo" variant="soft">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>

  <IconButton color="grass" variant="soft">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>

  <IconButton color="orange" variant="soft">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>
</Flex>

High-contrast

highContrast prop으로 배경과의 색 대비를 높여요.

<Flex direction="column" gap="3">
  <Flex gap="3">
    <IconButton color="gray" variant="classic">
      <MagnifyingGlassIcon width="18" height="18" />
    </IconButton>

    <IconButton color="gray" variant="solid">
      <MagnifyingGlassIcon width="18" height="18" />
    </IconButton>

    <IconButton color="gray" variant="soft">
      <MagnifyingGlassIcon width="18" height="18" />
    </IconButton>

    <IconButton color="gray" variant="surface">
      <MagnifyingGlassIcon width="18" height="18" />
    </IconButton>

    <IconButton color="gray" variant="outline">
      <MagnifyingGlassIcon width="18" height="18" />
    </IconButton>
  </Flex>

  <Flex gap="3">
    <IconButton color="gray" variant="classic" highContrast>
      <MagnifyingGlassIcon width="18" height="18" />
    </IconButton>

    <IconButton color="gray" variant="solid" highContrast>
      <MagnifyingGlassIcon width="18" height="18" />
    </IconButton>

    <IconButton color="gray" variant="soft" highContrast>
      <MagnifyingGlassIcon width="18" height="18" />
    </IconButton>

    <IconButton color="gray" variant="surface" highContrast>
      <MagnifyingGlassIcon width="18" height="18" />
    </IconButton>

    <IconButton color="gray" variant="outline" highContrast>
      <MagnifyingGlassIcon width="18" height="18" />
    </IconButton>
  </Flex>
</Flex>

Radius

radius prop으로 특정 radius 값을 지정해요.

<Flex gap="3">
  <IconButton radius="none" variant="soft">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>

  <IconButton radius="large" variant="soft">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>

  <IconButton radius="full" variant="soft">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>
</Flex>

Loading

loading prop으로 버튼 콘텐츠 대신 로딩 스피너를 표시해요. 로딩 중에는 버튼이 비활성화(disabled)돼요.

<Flex gap="3">
  <IconButton loading variant="classic">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>

  <IconButton loading variant="solid">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>

  <IconButton loading variant="soft">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>

  <IconButton loading variant="surface">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>

  <IconButton loading variant="outline">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>
</Flex>

더 알아보기 (Learn more)

Button 컴포넌트 — 텍스트가 있는 버튼
접근성 가이드 — 화면 리더 라벨링