Collapsible

Collapsible

추가 콘텐츠를 펼치거나 접을 때 사용하는 컴포넌트예요. 아코디언 같은 UI를 만들 때 유용해요.

출처: 문서

본문

사용법 (Usage)

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

<Collapsible.Root>
  <Collapsible.Trigger>
    <Collapsible.Indicator />
  </Collapsible.Trigger>
  <Collapsible.Content />
</Collapsible.Root>

예시 (Examples)

초기 열림 (Initial Open)

defaultOpen prop을 사용하면 콜랩시블을 기본적으로 열린 상태로 렌더링할 수 있어요.

부분 높이 (Partial Height)

collapsedHeight prop을 사용하면 접힌 상태에서 콘텐츠의 미리보기를 보여줄 수 있어요.

비활성화 (Disabled)

disabled prop을 사용하면 콜랩시블을 토글할 수 없게 만들 수 있어요.

제어 (Controlled)

open과 onOpenChange prop을 사용하면 콜랩시블 상태를 제어할 수 있어요.

스토어 (Store)

콜랩시블을 제어하는 또 다른 방법은 RootProvider 컴포넌트와 useCollapsible 스토어 훅을 사용하는 거예요.

지연 마운트 (Lazy Mounted)

unmountOnExit prop을 사용하면 접힐 때 콘텐츠를 언마운트할 수 있어요.

숨김 모드 (Hide Mode)

hideMode="activity"를 사용하면 접힌 콘텐츠를 마운트된 상태로 유지하면서 React가 그 하위 트리의 effects를 일시중지해요. 기본값인 display-none은 콘텐츠를 숨기지만 effects는 계속 실행되게 둬요.

이 모드는 React 19.2 이상이 필요하며, 이전 버전에서는 display-none으로 대체돼요. 또한 하위 트리를 숨기는 대신 제거하는 unmountOnExit과 함께 사용하면 효과가 없어요.

가이드 (Guides)

Collapsible context 접근

useCollapsibleContext를 사용하면 콜랩시블 안의 어떤 컴포넌트에서든 콜랩시블의 상태와 메서드에 접근할 수 있어요.

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

const CollapsibleStatus = () => {
  const collapsible = useCollapsibleContext()

  return <div>Collapsible is {collapsible.open ? "open" : "closed"}</div>
}

const MyCollapsible = () => (
  <Collapsible.Root>
    <Collapsible.Trigger>Toggle</Collapsible.Trigger>
    <Collapsible.Content>
      <CollapsibleStatus />
    </Collapsible.Content>
  </Collapsible.Root>
)

프로그래밍적으로 닫기

context에서 setOpen(false)를 사용하면 콜랩시블을 프로그래밍적으로 닫을 수 있어요.

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

const CloseButton = () => {
  const collapsible = useCollapsibleContext()

  return (
    <Button onClick={() => collapsible.setOpen(false)}>
      Close Collapsible
    </Button>
  )
}

const MyCollapsible = () => (
  <Collapsible.Root>
    <Collapsible.Trigger>Toggle</Collapsible.Trigger>
    <Collapsible.Content>
      <CloseButton />
    </Collapsible.Content>
  </Collapsible.Root>
)

콘텐츠 패딩 (Content Padding)

콜랩시블이 펼쳐지거나 접힐 때 애니메이션이 끊기는 것을 막으려면, Collapsible.Content에 직접 패딩을 적용하는 대신 안쪽 콘텐츠 요소에 패딩을 적용해서 애니메이션 중 시각적 떨림을 방지해 주세요.

이렇게 하세요 (DO THIS):

<Collapsible.Root>
  <Collapsible.Trigger>Toggle</Collapsible.Trigger>
  <Collapsible.Content>
    <Box padding="4" borderWidth="1px">
      {/* Content here */}
    </Box>
  </Collapsible.Content>
</Collapsible.Root>

이렇게 하지 마세요 (NOT THIS):

<Collapsible.Root>
  <Collapsible.Trigger>Toggle</Collapsible.Trigger>
  {/* ❌ Avoid applying padding directly to Content */}
  <Collapsible.Content padding="4" borderWidth="1px">
    {/* Content here */}
  </Collapsible.Content>
</Collapsible.Root>

Props

Root

Collapsible 컴포넌트의 Root 부분에 전달할 수 있는 prop을 확인해 주세요.

Explorer

Collapsible 컴포넌트의 각 부분을 인터랙티브하게 탐색해 보세요. 사이드바에서 부분을 클릭하면 미리보기에서 강조 표시돼요.

더 알아보기 (Learn more)

Chakra UI의 Collapsible 컴포넌트에 대해 더 자세히 알아보려면 공식 문서와 Ark UI Collapsible 문서를 확인해 보세요.