Group
하위 항목을 그룹으로 묶어 렌더링하고 항목별 값을 객체로 릴레이하는 컨테이너 컴포넌트
개요
Group은 여러 하위 항목을 flex 컨테이너로 묶어 배치하고, 각 항목의 값을 Record<key, value> 형태로 일괄 관리하는 컴포넌트입니다. items 기반 데이터 드리븐 렌더링과 children 자유 구성 모드를 모두 지원합니다.
주요 특징
- ✅ 데이터 드리븐: items 배열로 하위 항목을 선언적으로 정의
- ✅ 값 릴레이: value/onChange로 항목별 값을 객체 형태로 관리
- ✅ 커스텀 렌더링: renderItem으로 항목별 UI 자유 구성
- ✅ 비활성화: 전체(disabled) 및 항목별(item.disabled) 개별 제어
- ✅ 배치 제어: direction(가로/세로)과 gap으로 레이아웃 지정
- ✅ 자유 구성: children 모드로 임의 콘텐츠 배치 지원
기본 사용
items에 renderItem을 정의하면 각 항목의 value·onChange·disabled를 받아 UI를 렌더링합니다. 항목 값 변경 시 전체 값 객체가 onChange로 전달됩니다.
Preview
{"name":"","age":""}비활성화
disabled를 true로 설정하면 그룹 전체가 비활성화되고, renderItem에 전달되는 disabled도 true가 됩니다. 개별 항목만 비활성화하려면 item.disabled를 사용합니다.
Preview
자유 구성 (children)
children을 전달하면 items 없이 임의의 콘텐츠를 배치할 수 있습니다. direction="vertical"과 gap으로 레이아웃을 지정합니다.
Preview
항목 1
항목 2
항목 3
API Reference
Props
| Prop | Type | Default | Description |
|---|---|---|---|
items | GroupItem[] | - | 하위 항목 목록 |
value | Record<string, unknown> | {} | 항목별 값 객체 (항목 key → 값) |
disabled | boolean | false | 전체 비활성화 |
direction | "horizontal" | "vertical" | "horizontal" | 배치 방향 |
gap | number | string | - | 항목 간 간격 (number는 px로 적용) |
visible | boolean | true | 표시 여부 (false → 렌더 안 함) |
className | string | - | 컨테이너 CSS 클래스 |
children | ReactNode | - | 자유 구성 모드 (items 대신 사용) |
GroupItem
| Field | Type | Required | Description |
|---|---|---|---|
key | string | ✅ | 고유 키 (value 객체의 키) |
label | string | - | 항목 라벨 |
disabled | boolean | - | 개별 비활성화 |
renderItem | (props: { value: unknown; onChange: (value: unknown) => void; disabled: boolean }) => ReactNode | - | 커스텀 렌더링 |
renderItem이 없는 항목은 label ?? key 텍스트만 표시됩니다.
Events
| Event | Type | Description |
|---|---|---|
onChange | (value: Record<string, unknown>) => void | 항목 값 변경 콜백 (전체 객체) |
접근성
권장 사항
- ✅ 컨테이너에
role="group"이 자동 적용됨 - ✅ disabled 시
aria-disabled가 자동 반영됨 - ✅ renderItem 내부 입력 컨트롤에 적절한 label 또는 aria-label 제공
- ❌ disabled 전파에만 의존하지 말고, 내부 컨트롤의 disabled 속성도 함께 반영
관련 컴포넌트
Last updated on