Scroll Area

네이티브 스크롤 기능을 보강해 커스텀·크로스 브라우저 스타일링을 지원하는 컴포넌트예요.

출처: 문서

본문

스크롤 영역을 감싸서 커스텀 스크롤바를 만들 수 있게 해 주는 컴포넌트예요. 스크롤바가 콘텐츠 위에 떠서 공간을 차지하지 않고, 스크롤 자체는 네이티브로 동작하며 키보드 스크롤 같은 접근성 기능을 유지해요.

Features

스크롤바가 스크롤 가능한 콘텐츠 위에 떠서 공간을 차지하지 않아요.
스크롤은 네이티브; CSS 변환으로 기본 위치를 움직이지 않아요.
컨트롤과 상호작용할 때만 포인터 동작을 셔밍(보정)해서 키보드 컨트롤에 영향이 없어요.
오른쪽에서 왼쪽(RTL) 방향 지원.

Anatomy

모든 파트를 임포트해 조립해요.

import { ScrollArea } from "radix-ui";

export default () => (
  <ScrollArea.Root>
    <ScrollArea.Viewport />

    <ScrollArea.Scrollbar orientation="horizontal">
      <ScrollArea.Thumb />
    </ScrollArea.Scrollbar>

    <ScrollArea.Scrollbar orientation="vertical">
      <ScrollArea.Thumb />
    </ScrollArea.Scrollbar>

    <ScrollArea.Corner />
  </ScrollArea.Root>
);

API Reference

Root

스크롤 영역의 모든 파트를 담아요.

Prop	Type	Default
`asChild`	`boolean`	`false`
`type`	`enum`	`"hover"`
`scrollHideDelay`	`number`	`600`
`dir`	`enum`	No default value
`nonce`	`string`	No default value

Viewport

스크롤 영역의 뷰포트 영역이에요.

Prop	Type	Default
`asChild`	`boolean`	`false`

Scrollbar

세로 스크롤바예요. orientation prop을 가진 두 번째 Scrollbar를 추가하면 가로 스크롤을 켤 수 있어요.

Prop	Type	Default
`asChild`	`boolean`	`false`
`forceMount`	`boolean`	No default value
`orientation`	`enum`	`vertical`

Data attribute	Values
`[data-state]`	`"visible" \| "hidden"`
`[data-orientation]`	`"vertical" \| "horizontal"`

Thumb

ScrollArea.Scrollbar에 사용할 썸(thumb)이에요.

Prop	Type	Default
`asChild`	`boolean`	`false`

Data attribute	Values
`[data-state]`	`"visible" \| "hidden"`

Corner

세로/가로 스크롤바가 만나는 모서리예요.

Prop	Type	Default
`asChild`	`boolean`	`false`

Accessibility

대부분의 경우 네이티브 스크롤을 사용하고 CSS에서 제공되는 커스터마이즈 옵션에 의존하는 것이 가장 좋아요. 그것만으로 충분하지 않을 때 ScrollArea는 브라우저의 네이티브 스크롤 동작(그리고 키보드 스크롤 같은 접근성 기능)을 유지하면서 추가적인 커스터마이즈를 제공해요.

키보드 상호작용

컴포넌트가 네이티브 스크롤에 의존하므로 키보드 스크롤이 기본적으로 지원돼요. 특정 키보드 상호작용은 플랫폼마다 다를 수 있어 여기에서 명시하지 않고, 키 이벤트로 스크롤을 처리하는 특정 이벤트 리스너도 추가하지 않아요.

더 알아보기 (Learn more)

type="hover"가 기본이라 호버/스크롤 시에만 스크롤바가 보이고 scrollHideDelay로 숨김 지연을 조절할 수 있어요.
Select 같은 다른 primitive 안에서 커스텀 스크롤바를 조합할 때도 사용할 수 있어요.