Skip to Content

Group

하위 항목을 그룹으로 묶어 렌더링하고 항목별 값을 객체로 릴레이하는 컨테이너 컴포넌트


개요

Group은 여러 하위 항목을 flex 컨테이너로 묶어 배치하고, 각 항목의 값을 Record<key, value> 형태로 일괄 관리하는 컴포넌트입니다. items 기반 데이터 드리븐 렌더링과 children 자유 구성 모드를 모두 지원합니다.

주요 특징

  • 데이터 드리븐: items 배열로 하위 항목을 선언적으로 정의
  • 값 릴레이: value/onChange로 항목별 값을 객체 형태로 관리
  • 커스텀 렌더링: renderItem으로 항목별 UI 자유 구성
  • 비활성화: 전체(disabled) 및 항목별(item.disabled) 개별 제어
  • 배치 제어: direction(가로/세로)과 gap으로 레이아웃 지정
  • 자유 구성: children 모드로 임의 콘텐츠 배치 지원

기본 사용

itemsrenderItem을 정의하면 각 항목의 value·onChange·disabled를 받아 UI를 렌더링합니다. 항목 값 변경 시 전체 값 객체가 onChange로 전달됩니다.

{"name":"","age":""}

비활성화

disabled를 true로 설정하면 그룹 전체가 비활성화되고, renderItem에 전달되는 disabled도 true가 됩니다. 개별 항목만 비활성화하려면 item.disabled를 사용합니다.


자유 구성 (children)

children을 전달하면 items 없이 임의의 콘텐츠를 배치할 수 있습니다. direction="vertical"gap으로 레이아웃을 지정합니다.

항목 1
항목 2
항목 3

API Reference

Props

PropTypeDefaultDescription
itemsGroupItem[]-하위 항목 목록
valueRecord<string, unknown>{}항목별 값 객체 (항목 key → 값)
disabledbooleanfalse전체 비활성화
direction"horizontal" | "vertical""horizontal"배치 방향
gapnumber | string-항목 간 간격 (number는 px로 적용)
visiblebooleantrue표시 여부 (false → 렌더 안 함)
classNamestring-컨테이너 CSS 클래스
childrenReactNode-자유 구성 모드 (items 대신 사용)

GroupItem

FieldTypeRequiredDescription
keystring고유 키 (value 객체의 키)
labelstring-항목 라벨
disabledboolean-개별 비활성화
renderItem(props: { value: unknown; onChange: (value: unknown) => void; disabled: boolean }) => ReactNode-커스텀 렌더링

renderItem이 없는 항목은 label ?? key 텍스트만 표시됩니다.

Events

EventTypeDescription
onChange(value: Record<string, unknown>) => void항목 값 변경 콜백 (전체 객체)

접근성

권장 사항

  • ✅ 컨테이너에 role="group"이 자동 적용됨
  • ✅ disabled 시 aria-disabled가 자동 반영됨
  • ✅ renderItem 내부 입력 컨트롤에 적절한 label 또는 aria-label 제공
  • ❌ disabled 전파에만 의존하지 말고, 내부 컨트롤의 disabled 속성도 함께 반영

관련 컴포넌트

  • Form: 입력 컨트롤 격자 레이아웃 컨테이너
  • Box: 요약 정보 레이아웃 컨테이너
Last updated on