Skip to Content

ScrollArea

커스텀 스크롤바를 제공하는 스크롤 영역 컴포넌트


개요

ScrollArea 컴포넌트는 base-ui의 ScrollArea Primitive를 기반으로 네이티브 스크롤바를 커스텀 스크롤바로 대체합니다. Viewport, Scrollbar, Thumb, Corner로 구성되며 세로/가로 방향 스크롤을 모두 지원합니다.

주요 특징

  • 커스텀 스크롤바: 네이티브 스크롤바를 일관된 디자인의 스크롤바로 대체
  • 방향 제어: ScrollBar의 orientation으로 vertical, horizontal 지원
  • 자동 Corner: 양방향 스크롤 시 코너 영역 자동 렌더링
  • 포커스 링: Viewport 포커스 시 focus-visible 링 표시
  • 디자인 토큰: 테마 커스터마이징 지원

사용 예시

세로 스크롤

높이를 제한하고 세로로 스크롤 가능한 영역을 만듭니다.

가로 스크롤

가로 스크롤이 필요한 경우 ScrollBar를 orientation="horizontal"로 추가합니다.


양방향 스크롤과 Viewport 제어

scrollbars="both"로 양쪽 스크롤바를 자동 렌더링합니다. ref는 기존처럼 바깥 Root를 가리키며, 실제 스크롤 노드가 필요하면 viewportRef를 사용합니다. 아래 버튼은 Viewport를 이동시키고, onScrollevent.currentTarget에서 읽은 좌표를 표시합니다. viewportProps.onScroll도 함께 호출되어 카운터가 증가합니다.

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

PropTypeDefaultDescription
classNamestring-바깥 Root의 CSS 클래스
styleCSSProperties-바깥 Root 스타일 및 디자인 토큰
childrenReact.ReactNode-Viewport 안의 스크롤 콘텐츠
refRef<HTMLDivElement>-바깥 Root 참조 (기존 동작 유지)
viewportRefRef<HTMLDivElement>-실제 스크롤 가능한 Viewport 참조
viewportPropsOmit<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

EventTypeDescription
onScrollUIEventHandler<HTMLDivElement>Viewport 스크롤 이벤트. event.currentTarget.scrollTop / scrollLeft로 실제 좌표 조회
viewportProps.onScrollUIEventHandler<HTMLDivElement>최상위 onScroll과 함께 호출되는 Viewport 핸들러

ScrollBar Props

PropTypeDefaultDescription
orientation"vertical" | "horizontal""vertical"스크롤바 방향
classNamestring-추가 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" 명시
  • ❌ 페이지 전체 스크롤 대체 용도로 사용하지 않기

관련 컴포넌트

  • Separator: 스크롤 리스트 내부 항목 구분
  • Sidebar: SidebarContent 내부 스크롤 영역
Last updated on