Tree
계층(Hierarchy) 구조의 데이터를 트리 형태로 출력하는 컴포넌트 (체크박스, 검색, Drag & Drop 지원)
개요
iCignal Tree는 Foundation Tree의 기본 기능에 체크박스, 검색, Drag & Drop, 전체 펼침/접기, 다국어 대응, 노출 조건 제어 등 확장 기능을 제공합니다.
주요 특징
- ✅ 기본 트리 표시: 계층형 데이터를 트리 형태로 출력
- ✅ 펼침/접힘 아이콘: 하위 노드 존재 시 표시, 미존재 시 숨김
- ✅ 연결선(Lines): showLines로 노드 간 시각적 연결선 표시
- ✅ 들여쓰기: depth별 indent 간격 조절
- ✅ 포커스 상태: 선택된 노드 하이라이트
- ✅ 체크박스: 노드별 체크박스 표시 및 indeterminate 상태
- ✅ 전체 펼침: defaultExpandAll로 초기 로드 시 모든 노드 펼침
- ✅ 레벨별 펼침: defaultExpandLevel로 지정 depth까지 펼침, defaultExpandedIds와 병합 가능
- ✅ 검색: 노드명 기준 필터링, 경로 자동 펼침, 미포함 노드 숨김
- ✅ Drag & Drop: 노드 이동, 위치 표시, 이동 제한 규칙
- ✅ 다국어 대응: UI 텍스트 커스터마이징
- ✅ 노출 조건 제어: disabled로 노드 비활성화
- ✅ JSX Label: label에 ReactNode를 전달하여 커스텀 렌더링 (배지, 버튼 등)
- ✅ 행 배경색: rowClassName / getRowClassName으로 노드 행별 스타일 커스터마이징
사용 예시
기본 트리 표시
Preview
전체 펼침 (defaultExpandAll)
defaultExpandAll을 설정하면 초기 로드 시 모든 노드를 펼친 상태로 표시합니다.
Preview
레벨별 펼침 (defaultExpandLevel)
defaultExpandLevel을 설정하면 지정한 depth까지만 펼친 상태로 표시합니다. 예를 들어 defaultExpandLevel={1}은 루트 레벨의 부모 노드만 펼치고, defaultExpandLevel={2}는 depth 0, 1의 부모 노드까지 펼칩니다.
Preview
defaultExpandLevel=1
defaultExpandLevel=2
defaultExpandLevel + defaultExpandedIds 병합
defaultExpandLevel과 defaultExpandedIds를 함께 사용하면 두 설정의 합집합(union)으로 병합됩니다. defaultExpandAll이 함께 설정된 경우 defaultExpandAll이 우선합니다.
Preview
defaultExpandLevel=1 + defaultExpandedIds=["components"]
체크박스 표시
Preview
검색 기능
Preview
Drag & Drop
Preview
다국어 대응
Preview
노출 조건 제어
Preview
JSX Label
label에 문자열 대신 JSX를 전달할 수 있습니다. 검색 기능과 함께 사용할 경우 searchText를 지정하면 해당 텍스트로 검색됩니다.
Preview
행 배경색 (rowClassName)
Tree의 rowClassName prop으로 모든 행에 공통 스타일을 적용하고, TreeItem.rowClassName으로 개별 행에 배경색을 지정합니다.
Preview
행 배경색 - 동적 스타일 (getRowClassName)
getRowClassName 함수로 아이템/레벨에 따라 동적으로 행 스타일을 결정할 수 있습니다. 데이터에 rowClassName을 넣지 않고도 조건 분기가 가능합니다.
Preview
JSX Label + Button
label에 버튼을 포함할 수 있습니다. 버튼 클릭 시 e.stopPropagation()으로 노드 선택 이벤트와 분리합니다.
Preview
API Reference
Props
| Prop | Type | Default | Description |
|---|---|---|---|
items | TreeItem[] | - | 트리 데이터 배열 |
title | string | - | 트리 제목 |
defaultExpandedIds | string[] | [] | 초기 펼쳐진 노드 ID 목록 |
defaultExpandAll | boolean | false | 초기 로드 시 모든 노드 펼침 |
defaultExpandLevel | number | - | 지정 depth까지 초기 펼침 (0부터 시작, defaultExpandedIds와 병합) |
selectable | boolean | true | 노드 선택 가능 여부 |
multiple | boolean | false | 다중 선택 모드 |
showCheckbox | boolean | false | 체크박스 표시 여부 |
draggable | boolean | false | Drag & Drop 활성화 |
showLines | boolean | true | 노드 간 연결선 표시 여부 |
showIcons | boolean | false | 아이콘 표시 여부 |
showHeader | boolean | true | 헤더(전체펼침/접기) 표시 여부 |
showSearch | boolean | true | 검색 필드 표시 여부 |
indent | number | 20 | depth별 들여쓰기 간격 (px) |
selectedIds | string[] | - | 선택된 노드 ID (제어 모드) |
checkedIds | string[] | - | 체크된 노드 ID (제어 모드) |
expandAllLabel | string | "전체펼치기" | 전체 펼침 버튼 텍스트 |
collapseAllLabel | string | "전체접기" | 전체 접기 버튼 텍스트 |
searchPlaceholder | string | "Please input" | 검색 필드 플레이스홀더 |
className | string | - | 추가 CSS 클래스 |
rowClassName | string | - | 모든 노드 행에 공통 적용할 className |
getRowClassName | (item: TreeItem, level: number) => string | undefined | - | 아이템/레벨별 동적 행 className 함수 |
TreeItem
| Prop | Type | Description |
|---|---|---|
id | string | 노드 고유 ID |
label | ReactNode | 노드 표시 콘텐츠 (문자열 또는 JSX) |
searchText | string | label이 JSX일 때 검색에 사용할 텍스트 |
icon | ReactNode | 커스텀 아이콘 |
children | TreeItem[] | 하위 노드 배열 |
disabled | boolean | 비활성화 여부 |
rowClassName | string | 노드 행에 적용할 추가 className (배경색 등) |
TreeDropResult
| Prop | Type | Description |
|---|---|---|
nodeId | string | 이동한 노드 ID |
targetNodeId | string | null | 대상 노드 ID |
targetIndex | number | 대상 위치 인덱스 |
Events
| Event | Type | Description |
|---|---|---|
onSelectionChange | (selectedIds: string[]) => void | 선택 변경 시 호출 |
onCheckedChange | (checkedIds: string[]) => void | 체크 변경 시 호출 |
onItemsChange | (items: TreeItem[]) => void | 노드 이동 후 호출 |
onDrop | (result: TreeDropResult) => void | Drop 완료 시 호출 |
기본 사용법
import { Tree, type TreeItem } from "@vortex/ui-icignal"
const items: TreeItem[] = [
{
id: "root",
label: "Root",
children: [
{ id: "child-1", label: "Child 1" },
{ id: "child-2", label: "Child 2" },
],
},
]
<Tree
items={items}
selectable
showCheckbox
showSearch
draggable
/>접근성
권장 사항
- ✅ 노드 클릭으로 선택/펼침 동작 수행
- ✅ 포커스 상태가 시각적으로 구분됨
- ✅ 체크박스를 통한 다중 선택 지원
- ✅ 검색으로 원하는 노드에 빠르게 접근 가능
- ✅ JSX label 내 버튼은
e.stopPropagation()으로 노드 이벤트와 분리 - ❌ 깊은 중첩(5단계 이상)은 사용성 저하 주의
관련 컴포넌트
- Tree (Foundation): 기본 트리 컴포넌트 (선택, 연결선, 아이콘)
- Checkbox: 개별 체크박스 컴포넌트