TreeView

TreeView (트리 뷰)

계층적 데이터 구조를 접고 펼칠 수 있는 트리 형식으로 표시하는 컴포넌트예요. 폴더 구조나 사이트 내비게이션을 보여줄 때 유용해요.

출처: 문서

본문

TreeView는 계층적 데이터 구조를 접을 수 있는 트리 형식으로 보여 주는 컴포넌트예요. <ExampleTabs name="tree-view-basic" />

사용법 (Usage)

import { TreeView } from "@chakra-ui/react"

<TreeView.Root>
  <TreeView.Label />
  <TreeView.Tree>
    <TreeView.Branch>
      <TreeView.BranchControl>
        <TreeView.BranchIndicator />
        <TreeView.BranchText />
      </TreeView.BranchControl>
      <TreeView.BranchContent>
        <TreeView.BranchIndentGuide />
        <TreeView.Item />
      </TreeView.BranchContent>
    </TreeView.Branch>
    <TreeView.Item />
  </TreeView.Tree>
</TreeView.Root>

트리 뷰를 설정하려면 tree collection을 사용해 트리 데이터를 등록해야 해요.

단축 표현 (Shortcuts)

TreeView.Node

이 컴포넌트는 브랜치와 리프 노드의 재귀 렌더링을 관리하는 헬퍼예요.

<TreeView.Node
  showIndentGuide
  render={({ node, nodeState }) =>
    nodeState.isBranch ? (
      <TreeView.BranchControl>
        <TreeView.BranchText>{node.name}</TreeView.BranchText>
      </TreeView.BranchControl>
    ) : (
      <TreeView.Item>
        <TreeView.ItemText>{node.name}</TreeView.ItemText>
      </TreeView.Item>
    )
  }
/>

다음과 동일해요.

const TreeNode = (props: TreeView.NodeProviderProps<Node>) => {
  const { node, indexPath } = props
  return (
    <TreeView.NodeProvider key={node.id} node={node} indexPath={indexPath}>
      {node.children ? (
        <TreeView.Branch>
          <TreeView.BranchControl>
            <TreeView.BranchText>{node.name}</TreeView.BranchText>
          </TreeView.BranchControl>
          <TreeView.BranchContent>
            <TreeView.BranchIndentGuide />
            {node.children.map((child, index) => (
              <TreeNode
                key={child.id}
                node={child}
                indexPath={[...indexPath, index]}
              />
            ))}
          </TreeView.BranchContent>
        </TreeView.Branch>
      ) : (
        <TreeView.Item>
          <TreeView.ItemText>{node.name}</TreeView.ItemText>
        </TreeView.Item>
      )}
    </TreeView.NodeProvider>
  )
}

예시 (Examples)

크기 (Sizes)

size prop으로 트리 뷰의 크기를 바꿀 수 있어요.

변형 (Variants)

variant prop으로 트리 뷰의 변형을 바꿀 수 있어요.

색상 (Colors)

colorPalette prop으로 트리 뷰의 색상 팔레트를 바꿀 수 있어요.

비활성 노드 (Disabled Node)

노드의 속성에 disabled prop을 추가하면 해당 노드를 비활성화하고 상호작용을 막아요.

접기 제어 (Controlled Expansion)

expandedValue와 onExpandedChange prop으로 노드 확장 동작을 프로그래밍 방식으로 제어할 수 있어요.

명시적 확장 (Explicit Expand)

TreeView.BranchTrigger를 렌더링하면 노드 확장 동작을 수동으로 제어할 수 있어요.

접근성 문제를 피하려면 TreeView.BranchControl에 role="none"을 설정해야 할 수 있어요.

확장 아이콘 (Expand Icon)

nodeState.expanded prop으로 브랜치가 펼쳐졌을 때와 접혔을 때 렌더링할 아이콘을 바꿀 수 있어요.

들여쓰기 제거 (Remove Indentation)

--tree-indentation CSS 변수를 0px로 설정하면 트리 뷰의 들여쓰기를 제거할 수 있어요.

비동기 로딩 (Async Loading)

지연 로딩은 노드의 자식들을 필요할 때(또는 비동기로) 불러오는 기능이에요. 초기 로드 시간과 메모리 사용량을 개선하는 데 도움을 줘요.

이를 사용하려면 다음을 제공해야 해요.

  • loadChildren — 노드의 자식을 불러오는 함수예요.
  • onLoadChildrenComplete — 노드의 자식이 로드됐을 때 호출되는 콜백이에요. 트리 컬렉션을 업데이트하는 데 사용돼요.
  • childrenCount — 브랜치 노드의 자식 수를 나타내는 숫자예요.

필터링 (Filtering)

필터링은 큰 트리가 있고 검색어와 일치하는 노드만 표시하고 싶을 때 유용해요. TreeCollection의 filter 메서드와 useFilter 훅을 조합해 노드를 필터링하는 예시예요.

접기 애니메이션 (Collapse Animation)

animateContent prop으로 트리 뷰 콘텐츠의 확장/축소 상태를 애니메이션할 수 있어요.

전체 확장/축소 (Expand/Collapse All)

한 번에 모든 노드를 확장하거나 축소하는 컨트롤을 제공할 수 있어요.

스토어 (Store)

useTreeView 훅으로 트리 뷰 스토어를 만들고 이를 TreeView.RootProvider 컴포넌트에 넘길 수 있어요. 이렇게 하면 트리 뷰를 프로그래밍 방식으로 최대한 제어할 수 있어요.

링크 (Links)

TreeView.Item 컴포넌트의 asChild prop을 활용해 트리 아이템을 링크로 렌더링할 수 있어요.

다중 선택 (Multi Select)

TreeView.Root 컴포넌트에 selectionMode="multiple" prop을 추가하면 다중 선택 기능을 활성화할 수 있어요.

Info: 이 모드에서는 여러 아이템을 선택하려면 보조 키(modifier key)를 눌러야 해요.

  • macOS에서 Ctrl 또는 ⌘를 누른 채 아이템을 클릭하세요.
  • 아이템 하나를 클릭한 뒤, 다른 아이템을 클릭할 때 Shift를 누른 채 클릭하세요.

체크박스 트리 (Checkbox Tree)

트리 노드에 체크박스를 추가해 선택 기능을 제공할 수 있어요.

변경 (Mutation)

트리 뷰에서 노드를 추가/제거하도록 설계하는 예시예요.

커스텀 아이콘 (Custom Icon)

트리 뷰의 데이터에 따라 커스텀 아이콘을 렌더링하는 예시예요.

Props

TreeView 컴포넌트의 Root, Node 파트 props에 대한 상세 정보는 공식 문서의 PropTable를 참고하세요.

더 알아보기 (Learn more)