Tree

Foundation Tree를 래핑한 CALS 전용 트리 컴포넌트입니다.

접기/펼치기 가능한 헤더, 실시간 필터 검색, 데이터 속성 매핑, 스타일 오버라이드를 지원합니다.

주요 기능

BasicUI: 계층 구조 데이터를 트리로 표시
검색: 인라인 필터(filter) / 조건 검색(static) / 검색 없음(none)
전체 펼치기/접기: 헤더 버튼으로 모든 노드를 한 번에 제어
접기 잠금: collapseDisabled로 항상 펼침 상태 고정
데이터 매핑: idKey, labelKey, childrenKey로 외부 데이터 필드 매핑
스타일 오버라이드: 배경색, 글자색, 글꼴, 크기, 테두리 등
빈 상태: 데이터 없을 시 커스텀 메시지 표시

기본 사용


import { Tree } from "@vortex/ui-cals"
 
const items = [
  {
    id: "1",
    label: "부서 A",
    children: [
      { id: "1-1", label: "팀 1" },
      { id: "1-2", label: "팀 2" },
    ],
  },
  { id: "2", label: "부서 B" },
]
 
<Tree items={items} title="조직도" />

인터랙티브 예시

기본 트리

조직도

부서 A

부서 B

부서 C

필터 검색

검색 포함

부서 A

부서 B

부서 C

전체 펼침

초기 전체 펼침

부서 A

팀 1

팀 2

파트 A

파트 B

부서 B

팀 3

부서 C

도구 모음

도구 모음 포함

부서 A

부서 B

부서 C

스타일 오버라이드

배경색 + 글자색

부서 A

부서 B

부서 C

빈 상태

빈 트리

데이터가 없습니다

API Reference

Props

Prop	Type	Default	Description
`items`	`TreeDataItem[]`	`[]`	트리 데이터 배열
`title`	`ReactNode`	-	헤더 영역에 표시할 제목
`visible`	`boolean`	`true`	화면 표시 여부 (false → 렌더 안 함)
`treeExpandAll`	`boolean`	`false`	초기 전체 펼침 상태
`collapseDisabled`	`boolean`	`false`	접기 잠금 — true이면 항상 펼쳐진 상태로 고정
`defaultCollapsed`	`boolean`	`false`	초기 접힌 상태 (collapseDisabled 시 무시)
`searchType`	`"filter" \| "static" \| "none"`	`"none"`	검색 유형
`searchContent`	`ReactNode`	-	static 검색 시 표시할 검색 폼
`readOnly`	`boolean`	`false`	읽기 전용 (검색 입력 disabled)
`labelKey`	`string`	`"label"`	표시 이름으로 사용할 데이터 필드명
`idKey`	`string`	`"id"`	식별자로 사용할 데이터 필드명
`childrenKey`	`string`	`"children"`	하위 항목으로 사용할 데이터 필드명
`actions`	`ReactNode`	-	헤더 도구 모음 영역에 렌더링할 커스텀 요소
`backgroundColor`	`string`	-	컨테이너 배경색
`color`	`string`	-	컨테이너 글자색
`fontFamily`	`string`	-	트리 콘텐츠 글꼴
`fontSize`	`string`	-	트리 콘텐츠 글자 크기
`fontWeight`	`string \| number \| boolean`	-	글꼴 굵기 (truthy 시 500 고정)
`fontStyle`	`string`	-	글꼴 스타일 (italic 등)
`borderColor`	`string`	-	검색 입력 테두리 색상
`borderWidth`	`string`	-	검색 입력 테두리 두께
`height`	`string`	-	트리 영역 높이 (설정 시 overflow: auto 적용)
`className`	`string`	-	컨테이너 CSS 클래스
`style`	`CSSProperties`	-	인라인 스타일
`emptyText`	`string`	`"데이터가 없습니다"`	데이터 없을 시 표시할 빈 상태 메시지

Events

Event	Type	Description
`onNodeClick`	`(node: TreeDataItem) => void`	노드 클릭 시 원본 데이터 전달
`onSearch`	`(keyword: string) => void`	static 검색에서 Enter 입력 시
`onExpandAll`	`() => void`	전체 펼치기 버튼 클릭 시
`onCollapseAll`	`() => void`	전체 접기 버튼 클릭 시

TreeDataItem


type TreeDataItem = Record<string, unknown>

외부 데이터 형태를 자유롭게 사용할 수 있도록 제네릭 Record 타입입니다. idKey, labelKey, childrenKey prop으로 실제 사용할 필드를 매핑합니다.

접근성

권장 사항

✅ 헤더 영역에 role="button", tabIndex=0이 자동 적용되어 키보드로 접기/펼치기 가능
✅ 전체 펼치기/접기 버튼에 aria-label 자동 제공 (“전체 펼치기”, “전체 접기”)
✅ Foundation Tree 내부에서 role="tree", role="treeitem" 시맨틱 자동 적용
✅ collapseDisabled 시 트리거에 disabled 속성 부여
❌ 대량 노드 시 height를 설정하여 스크롤 영역을 제한하는 것을 권장

Tree

주요 기능

기본 사용

인터랙티브 예시

기본 트리

조직도

필터 검색

검색 포함

전체 펼침

초기 전체 펼침

도구 모음

도구 모음 포함

스타일 오버라이드

배경색 + 글자색

빈 상태

빈 트리

API Reference

Props

Events

TreeDataItem

접근성

권장 사항

관련 컴포넌트