ScrollArea
커스텀 스크롤바를 제공하는 스크롤 영역 컴포넌트
개요
ScrollArea 컴포넌트는 base-ui의 ScrollArea Primitive를 기반으로 네이티브 스크롤바를 커스텀 스크롤바로 대체합니다. Viewport, Scrollbar, Thumb, Corner로 구성되며 세로/가로 방향 스크롤을 모두 지원합니다.
주요 특징
- ✅ 커스텀 스크롤바: 네이티브 스크롤바를 일관된 디자인의 스크롤바로 대체
- ✅ 방향 제어: ScrollBar의 orientation으로 vertical, horizontal 지원
- ✅ 자동 Corner: 양방향 스크롤 시 코너 영역 자동 렌더링
- ✅ 포커스 링: Viewport 포커스 시
focus-visible링 표시 - ✅ 디자인 토큰: 테마 커스터마이징 지원
사용 예시
세로 스크롤
높이를 제한하고 세로로 스크롤 가능한 영역을 만듭니다.
Preview
가로 스크롤
가로 스크롤이 필요한 경우 ScrollBar를 orientation="horizontal"로 추가합니다.
Preview
양방향 스크롤과 Viewport 제어
scrollbars="both"로 양쪽 스크롤바를 자동 렌더링합니다. ref는 기존처럼 바깥 Root를 가리키며, 실제 스크롤 노드가 필요하면 viewportRef를 사용합니다. 아래 버튼은 Viewport를 이동시키고, onScroll의 event.currentTarget에서 읽은 좌표를 표시합니다. viewportProps.onScroll도 함께 호출되어 카운터가 증가합니다.
Preview
scrollLeft: 0px · scrollTop: 0px · viewportProps.onScroll: 0회
스크롤바 디자인 토큰
Foundation ScrollArea의 style에 아래 토큰을 지정하면 자동 또는 명시적으로 렌더링된 실제 ScrollBar와 Thumb에 적용됩니다. 중첩된 CALS 컴포넌트를 꾸밀 때는 List 예제처럼 해당 범위의 [data-token="scroll-area"] 루트를 직접 선택하세요.
| Token | 적용 대상 |
|---|---|
--scroll-area-scrollbar-width-vertical | 세로 스크롤바 너비 |
--scroll-area-scrollbar-height-horizontal | 가로 스크롤바 높이 |
--scroll-area-thumb-background | 스크롤 thumb 배경색 |
API Reference
ScrollArea Props
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | - | 바깥 Root의 CSS 클래스 |
style | CSSProperties | - | 바깥 Root 스타일 및 디자인 토큰 |
children | React.ReactNode | - | Viewport 안의 스크롤 콘텐츠 |
ref | Ref<HTMLDivElement> | - | 바깥 Root 참조 (기존 동작 유지) |
viewportRef | Ref<HTMLDivElement> | - | 실제 스크롤 가능한 Viewport 참조 |
viewportProps | Omit<ScrollAreaPrimitive.Viewport.Props, "children" | "ref"> | - | Viewport의 className, style, 접근성 속성, 이벤트 핸들러 |
scrollbars | "vertical" | "horizontal" | "both" | "vertical" | 자동 렌더링할 스크롤바 방향 |
base-ui
ScrollArea.Root의 props를 지원합니다. 단, 최상위onScroll은 Root가 아닌 내부 Viewport에 연결됩니다.ScrollAreaPrimitive는@base-ui/react/scroll-area의 타입을 가리킵니다. Viewport와 Corner는 내부에서 구성되며, 기존<ScrollBar orientation="horizontal" />합성 방식도 사용할 수 있습니다.
ScrollArea Events
| Event | Type | Description |
|---|---|---|
onScroll | UIEventHandler<HTMLDivElement> | Viewport 스크롤 이벤트. event.currentTarget.scrollTop / scrollLeft로 실제 좌표 조회 |
viewportProps.onScroll | UIEventHandler<HTMLDivElement> | 최상위 onScroll과 함께 호출되는 Viewport 핸들러 |
ScrollBar Props
| Prop | Type | Default | Description |
|---|---|---|---|
orientation | "vertical" | "horizontal" | "vertical" | 스크롤바 방향 |
className | string | - | 추가 CSS 클래스 |
기본 사용법
import { ScrollArea, ScrollBar } from "@vortex/ui-foundation"
// 세로 스크롤 (기본)
<ScrollArea className="h-72 w-48 rounded-md border">
<div className="p-4">{/* 콘텐츠 */}</div>
</ScrollArea>
// 가로 스크롤 추가
<ScrollArea className="w-96 whitespace-nowrap rounded-md border">
<div className="flex w-max space-x-4 p-4">{/* 콘텐츠 */}</div>
<ScrollBar orientation="horizontal" />
</ScrollArea>접근성
키보드 지원
- Viewport가 포커스 가능하며 방향키로 스크롤 가능
focus-visible시 아웃라인과 링이 표시되어 포커스 위치 확인 가능
권장 사항
- ✅ 스크롤 영역에 명확한 높이/너비 지정
- ✅ 가로 스크롤 사용 시
ScrollBar orientation="horizontal"명시 - ❌ 페이지 전체 스크롤 대체 용도로 사용하지 않기