Skip to Content
ComponentsFoundationButtonGroup

ButtonGroup

관련된 버튼들을 하나의 그룹으로 묶어 표시하는 컴포넌트

개요

ButtonGroup 컴포넌트는 연관된 버튼들을 시각적으로 하나의 그룹으로 묶어 표시합니다. 그룹 내 버튼들은 경계선이 자연스럽게 연결되고 모서리 radius가 자동으로 조정됩니다.

주요 특징

  • ✅ 방향 제어: horizontal, vertical 방향 지원
  • ✅ 크기 옵션: xs, sm, md, lg, xl 사이즈로 그룹 radius 조정
  • ✅ 자동 스타일링: 그룹 내 버튼의 모서리와 테두리 자동 병합
  • ✅ 보조 요소: ButtonGroupText, ButtonGroupSeparator 지원
  • ✅ 시맨틱 마크업: role="group" 자동 적용
  • ✅ 디자인 토큰: CSS 변수 기반 테마 커스터마이징 지원

사용 예시

기본 사용법

관련된 액션 버튼들을 가로로 묶습니다.

아이콘 버튼 그룹

텍스트 서식 도구처럼 아이콘 버튼들을 묶을 수 있습니다.

세로 방향

orientation="vertical"로 버튼을 세로로 쌓습니다.

텍스트 레이블 포함

ButtonGroupText로 그룹에 레이블을 붙일 수 있습니다.

정렬

구분선 포함

ButtonGroupSeparator로 그룹 내 버튼 사이에 구분선을 추가합니다.

Sizes

size prop으로 그룹의 모서리 radius를 Button 크기에 맞게 조정합니다.

API Reference

ButtonGroup Props

PropTypeDefaultDescription
orientation"horizontal" | "vertical""horizontal"버튼 그룹 방향
size"xs" | "sm" | "md" | "lg" | "xl""md"그룹 모서리 radius 크기
classNamestring-추가 CSS 클래스

div 요소의 모든 HTML 속성을 지원합니다.

ButtonGroupText Props

PropTypeDefaultDescription
size"xs" | "sm" | "md" | "lg" | "xl""md"텍스트 블록 크기
classNamestring-추가 CSS 클래스

ButtonGroupSeparator Props

Separator 컴포넌트의 props를 지원합니다.

PropTypeDefaultDescription
orientation"horizontal" | "vertical""vertical"구분선 방향
classNamestring-추가 CSS 클래스

기본 사용법

import { Button, ButtonGroup } from "@vortex/ui-foundation"
 
<ButtonGroup>
  <Button variant="outline">왼쪽</Button>
  <Button variant="outline">가운데</Button>
  <Button variant="outline">오른쪽</Button>
</ButtonGroup>

접근성

시맨틱 마크업

  • role="group"이 자동 적용되어 관련 버튼들이 하나의 그룹임을 나타냅니다
  • 그룹의 용도가 명확하지 않은 경우 aria-label로 그룹 이름을 제공하세요

권장 사항

  • ✅ 아이콘만 있는 버튼에는 aria-label 필수 제공
  • ✅ 그룹 내 버튼은 서로 관련된 액션으로 구성
  • ✅ 포커스 시 개별 버튼이 그룹 위로 올라와 포커스 링이 잘리지 않음
  • ❌ 서로 무관한 버튼을 하나의 그룹으로 묶지 않기

관련 컴포넌트

Last updated on
ButtonCalendar