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="조직도" />

ScrollArea 내부 스크롤

Tree의 노드 영역은 Foundation ScrollArea / ScrollBar를 사용합니다. 기존 height, fullSize, 검색, 선택, 접기/펼치기 API는 그대로 유지됩니다. 높이를 지정하면 노드 영역만 스크롤되고 헤더와 검색 영역은 고정됩니다.

스크롤바 스타일은 List 예제처럼 Tree를 감싼 요소에서 중첩된 [data-token="scroll-area"]에 Foundation 토큰을 지정합니다. 부모 style에서 상속시키는 대신 실제 ScrollArea 루트를 선택하면 내부 기본 토큰에 덮어써지지 않습니다.

인터랙티브 예시

기본 트리

부서 A

부서 B

부서 C

필터 검색

부서 A

부서 B

부서 C

아이콘 표시

부서 A

부서 B

부서 C

전체 펼침 · ScrollArea

부서 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"`	검색 유형
`searchPlaceholder`	`string`	-	검색 입력 placeholder
`searchContent`	`ReactNode`	-	static 검색 시 표시할 검색 폼
`readOnly`	`boolean`	`false`	읽기 전용 (검색 입력 disabled)
`showIcons`	`boolean`	`false`	노드 아이콘 표시 여부
`expandOnNodeClick`	`boolean`	`false`	행을 누르면 선택과 함께 펼침·접힘
`showLines`	`boolean`	`true`	연결선 표시
`indent`	`number`	`20`	단계별 들여쓰기(px)
`animateExpand`	`boolean`	`true`	펼침 애니메이션
`labelKey`	`string`	`"label"`	표시 이름으로 사용할 데이터 필드명
`idKey`	`string`	`"id"`	식별자로 사용할 데이터 필드명
`childrenKey`	`string`	`"children"`	하위 항목으로 사용할 데이터 필드명
`iconKey`	`string`	-	아이콘 필드명 (값을 노드 아이콘으로 표시)
`renderLabel`	`(item: TreeItem, original: TreeDataItem) => ReactNode`	-	노드 라벨 렌더러. 변환된 노드와 원본 데이터를 받는다
`renderIcon`	`(item: TreeItem, hasChildren: boolean) => ReactNode`	-	노드 아이콘 렌더러
`actions`	`ReactNode`	-	헤더 도구 모음 영역에 렌더링할 커스텀 요소
`backgroundColor`	`string`	-	컨테이너 배경색
`color`	`string`	-	컨테이너 글자색
`fontFamily`	`string`	-	트리 콘텐츠 글꼴
`fontSize`	`string`	-	트리 콘텐츠 글자 크기
`fontWeight`	`string \| number \| boolean`	-	글꼴 굵기 (truthy 시 500 고정)
`fontStyle`	`string`	-	글꼴 스타일 (italic 등)
`borderColor`	`string`	-	검색 입력 테두리 색상
`borderWidth`	`string`	-	검색 입력 테두리 두께
`fullSize`	`boolean`	`false`	부모 컨테이너 높이에 맞춰 채우기(지정 시 `height` 무시)
`height`	`string`	-	내부 ScrollArea 높이
`className`	`string`	-	컨테이너 CSS 클래스
`style`	`CSSProperties`	-	인라인 스타일
`emptyText`	`string`	`"데이터가 없습니다"`	데이터 없을 시 표시할 빈 상태 메시지

Events

Event	Type	Description
`onNodeClick`	`(node: TreeDataItem) => void`	노드 클릭 시 원본 데이터 전달
`onSearch`	`(keyword: string) => void`	filter 검색 입력에서 Enter 시 앞뒤 공백을 뺀 검색어로 호출(static 검색에서는 호출 안 함)
`onExpandAll`	`() => void`	전체 펼치기 버튼 클릭 시
`onCollapseAll`	`() => void`	전체 접기 버튼 클릭 시

Ref (TreeRef)

메서드/속성	Type	Description
`expandAll()`	`() => void`	모든 노드를 펼친다. 헤더 「전체 펼치기」와 같고 `onExpandAll`도 불린다
`collapseAll()`	`() => void`	모든 노드를 접는다. 헤더 「전체 접기」와 같고 `onCollapseAll`도 불린다. 검색 중이면 그 검색어 동안 결과 상위 펼침도 접는다
`focus()`	`() => void`	트리 영역에 포커스(트리 영역은 포커스를 받지 않아 동작하지 않는다)
`blur()`	`() => void`	포커스 해제
`element`	`HTMLElement \| null`	트리 영역(`data-slot="tree-content"`) 요소

소비자가 만든 버튼에서 부른다.


const treeRef = useRef<TreeRef>(null)
 
<Button onClick={() => treeRef.current?.expandAll()}>전체 펼치기</Button>
<Tree ref={treeRef} items={items} />

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

주요 기능

기본 사용

ScrollArea 내부 스크롤

인터랙티브 예시

기본 트리

조직도

필터 검색

검색 포함

아이콘 표시

노드 아이콘 포함

전체 펼침 · ScrollArea

초기 전체 펼침

도구 모음

도구 모음 포함

스타일 오버라이드

배경색 + 글자색

빈 상태

빈 트리

API Reference

Props

Events

Ref (TreeRef)

TreeDataItem

접근성

권장 사항

관련 컴포넌트