Box
아이콘·수치·레이블로 구성된 요약 정보를 하나의 박스 형태로 제공하는 레이아웃 컨테이너
개요
BoxIcon·BoxData·BoxLabel 등 하위 컴포넌트를 조합하여 대시보드 카드 형태의 요약 정보를 표시하는 레이아웃 컨테이너입니다.
주요 특징
- ✅ Auto 모드: data/label/icon prop만으로 BoxIcon·BoxData·BoxLabel 자동 생성
- ✅ Manual 모드: children으로 직접 구성 (자유 레이아웃)
- ✅ 아이콘 위치 설정: top/bottom/left/right 4방향 배치
- ✅ 클릭 이벤트: onClick 지정 시 포인터 커서 + 키보드 접근성 자동 적용
- ✅ 배경색 오버라이드: backgroundColor prop
- ✅ 가시성 제어: visible prop으로 선언적 표시/숨김
Auto 모드 (기본 사용)
data, label, icon prop만 지정하면 내부적으로 BoxIcon·BoxData·BoxLabel을 자동 생성합니다.
Preview
1,234건
Manual 모드 (children)
children을 지정하면 auto 모드 대신 직접 구성합니다. BoxIcon·BoxData·BoxLabel을 자유롭게 배치할 수 있습니다.
Preview
1,234건
아이콘 위치 (iconPosition)
iconPosition prop으로 아이콘 배치 방향을 설정합니다. 기본값은 "right" (콘텐츠 좌측, 아이콘 우측).
Preview
클릭 이벤트 (onClick)
onClick prop을 지정하면 포인터 커서가 표시되며, role=“button”과 tabIndex가 자동으로 부여됩니다. Enter/Space 키보드 조작도 지원합니다.
Preview
배경색 (backgroundColor)
backgroundColor prop으로 박스 배경색을 오버라이드합니다.
Preview
100%
85%
3건
가시성 제어 (visible)
visible prop으로 선언적으로 표시/숨김을 제어합니다.
Preview
API Reference
Props
| Prop | Type | Default | Description |
|---|---|---|---|
icon | ReactNode | - | 아이콘 콘텐츠 (auto 모드 시 BoxIcon으로 래핑) |
iconProps | Omit<BoxIconProps, 'icon'> | - | auto 모드 시 BoxIcon에 전달할 추가 props |
iconPosition | "top" | "bottom" | "left" | "right" | "right" | 아이콘 배치 위치 |
data | string | number | - | auto 모드: BoxData에 표시할 데이터 값 |
dataProps | Omit<BoxDataProps, 'data' | 'suffix'> | - | auto 모드: BoxData에 전달할 추가 props |
label | string | - | auto 모드: BoxLabel에 표시할 라벨 텍스트 |
labelProps | Omit<BoxLabelProps, 'title'> | - | auto 모드: BoxLabel에 전달할 추가 props |
suffix | string | - | auto 모드 시 BoxData에 전달되는 접미어 |
children | ReactNode | - | 콘텐츠 영역 (지정 시 auto 모드 무시, manual 모드로 동작) |
visible | boolean | true | 표시 여부 (false면 렌더링 안 함) |
onClick | (e: MouseEvent) => void | - | 박스 클릭 핸들러 |
backgroundColor | string | - | 박스 배경색 오버라이드 |
className | string | - | 컨테이너에 적용할 CSS 클래스 |
style | CSSProperties | - | 인라인 스타일 |
title | string | - | HTML title (네이티브 툴팁) |
접근성
자동 적용 (onClick 지정 시)
- ✅
role="button"자동 부여 - ✅
tabIndex={0}으로 키보드 포커스 가능 - ✅ Enter/Space 키로 클릭 이벤트 발생
- ✅
cursor-pointer시각적 표시
권장 사항
- ✅ 클릭 가능한 Box에는 title prop으로 설명 제공
- ❌ 중요 정보를 색상만으로 전달하지 않기
관련 컴포넌트
Last updated on