ScrollArea

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

개요

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

주요 특징

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

사용 예시

세로 스크롤

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

<ScrollArea className="h-56 w-48 rounded-md border">
  <div className="p-4">
    <h4 className="mb-4 text-sm leading-none font-medium">태그</h4>
    <div className="text-sm">v1.2.0-beta.5</div>
    <Separator className="my-2" />
    <div className="text-sm">v1.2.0-beta.4</div>
    <Separator className="my-2" />
    {/* ... */}
  </div>
</ScrollArea>

가로 스크롤

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

<ScrollArea className="w-72 rounded-md border whitespace-nowrap">
  <div className="flex w-max space-x-4 p-4">
    <div className="bg-muted flex h-24 w-32 shrink-0 items-center justify-center rounded-md">
      항목 1
    </div>
    {/* ... */}
  </div>
  <ScrollBar orientation="horizontal" />
</ScrollArea>

API Reference

ScrollArea Props

base-ui ScrollArea.Root의 모든 props를 지원합니다. 내부에 Viewport, 세로 ScrollBar, Corner가 자동으로 포함됩니다.

ScrollBar Props

기본 사용법

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 내부 스크롤 영역