Scroll Area

Scroll Area (스크롤 영역)

Scroll Area는 커스텀 스타일의 스크롤바로 스크롤 가능한 영역을 만들 때 사용해요. 스크롤바의 표시, 크기, 동작을 다양하게 제어할 수 있어요.

출처: 문서

본문

사용법 (Usage)

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

<ScrollArea.Root>
  <ScrollArea.Viewport>
    <ScrollArea.Content />
  </ScrollArea.Viewport>
  <ScrollArea.Scrollbar>
    <ScrollArea.Thumb />
  </ScrollArea.Scrollbar>
  <ScrollArea.Corner />
</ScrollArea.Root>

예시 (Examples)

변형 (Variants)

variant prop을 사용해 스크롤바 표시 동작을 바꿀 수 있어요. 값은 hover(기본값) 또는 always 중 하나예요.

크기 (Sizes)

size prop을 사용해 스크롤 영역의 크기를 바꿀 수 있어요. 이는 스크롤바 두께와 콘텐츠 패딩에 영향을 줘요.

가로 스크롤 (Horizontal Scrolling)

스크롤 영역은 콘텐츠가 가로로 넘칠 때 가로 스크롤을 자동으로 지원해요.

양방향 (Both Directions)

콘텐츠가 양방향으로 넘치면 두 스크롤바가 모두 나타나요.

:::info

ScrollArea.Corner 컴포넌트를 렌더링해 두 스크롤바의 교차 지점을 채우는 모서리 인디케이터를 보여주면, 매끄럽고 깔끔한 스타일을 만들 수 있어요.

:::

스크롤 그림자 (Scroll Shadow)

콘텐츠가 스크롤 가능할 때 시각적 피드백을 주려면 mask-image를 사용해 가장자리에 나타나는 스크롤 그림자를 구현할 수 있어요.

data-overflow-y 속성을 사용해 실제로 넘칠 때만 그림자를 표시하게 할 수 있어요 — 이렇게 하면 항목이 하나뿐이거나 스크롤할 콘텐츠가 없을 때 그림자가 나타나지 않아요.

썸 스타일링 (Thumb Styling)

스크롤바 썸(thumb)의 모양과 색상을 다양한 스타일로 커스터마이즈할 수 있어요.

하단 고정 (Stick to Bottom)

새 콘텐츠가 자동으로 하단으로 스크롤되지만, 사용자가 수동으로 스크롤할 수도 있는 채팅 스타일 동작을 구현할 수 있어요.

이 예시는 스크롤 핀 고정에 use-stick-to-bottom을 사용해요.

가상화 (Virtualization)

@tanstack/react-virtual을 사용해 보이는 항목만 렌더링함으로써 큰 데이터셋을 효율적으로 처리할 수 있어요.

스토어 (Store)

스크롤 영역을 외부 상태 관리와 프로그래밍 방식 제어와 함께 사용할 수 있어요.

한쪽으로 스크롤 (Scroll to Side)

여러 방향과 위치로 스크롤하면서 콘텐츠를 프로그래밍 방식으로 탐색할 수 있어요.

위치로 스크롤 (Scroll to Position)

부드러운 애니메이션으로 스크롤 영역 안의 특정 위치나 항목으로 점프할 수 있어요.

RTL 지원 (RTL Support)

스크롤 영역 컴포넌트는 아랍어나 히브리어 같은 오른쪽에서 왼쪽(Right-to-Left, RTL) 언어를 완전히 지원해요.

메뉴와 함께 (With Menu)

스크롤 영역을 메뉴 같은 다른 컴포넌트와 결합해 넘치는 콘텐츠를 처리할 수 있어요. 이 예시는 항목이 많은 스크롤 가능한 메뉴를 만드는 방법을 보여줘요.

Props

ScrollArea의 Root, Viewport, Content, Scrollbar, Thumb, Corner 파트에서 사용 가능한 props는 공식 문서에서 확인할 수 있어요.