Component

ScrollArea

내용이 넘치면 스크롤바를 표시하는 영역입니다.

Playground

옵션을 조절하며 화면과 사용 코드를 함께 확인하세요.

PC 1280px

Controls

렌더할 scrollbar 방향

scrollbar 표시 시점

샘플 항목 수

Code

import { type ScrollAreaProps, ScrollArea } from '@amineslab/ui'

import { type ReactNode, type CSSProperties, type ComponentPropsWithoutRef } from 'react'

import { cn } from '@amineslab/ui/utils'

function ExampleScrollListItem({ className, ...props }: ComponentPropsWithoutRef<'li'>) {
    return (<li {...props} className={cn('rounded-action px-2.5 py-2 text-body-2 hover:bg-interactive-item-hover', className)}/>);
}

interface ExampleScrollListProps extends Omit<ScrollAreaProps, 'children'> {
    children: ReactNode;
    listStyle?: CSSProperties;
}

function ExampleScrollList({ children, className, listStyle, ...props }: ExampleScrollListProps) {
    return (<ScrollArea {...props} className={cn('h-40 w-full max-w-80 rounded-section border border-elevation-700 bg-section-primary', className)}>
      <ul className="m-0 list-none p-2" style={listStyle}>
        {children}
      </ul>
    </ScrollArea>);
}

export default function ExamplePreview() {
  return ((<ExampleScrollList scrollHideDelay={600} listStyle={{ width: undefined }} orientation={"vertical"} type={"hover"}>
      {Array.from({ length: 12 }, (_, index) => (<ExampleScrollListItem key={`release-${index + 1}`}>
          v0.{index + 1}.0 릴리즈 노트
        </ExampleScrollListItem>))}
    </ExampleScrollList>))
}

Props

@amineslab/ui에서 ScrollArea를 가져옵니다.

import { ScrollArea } from '@amineslab/ui'

`ScrollArea`

HTML <div> 요소의 표준 속성을 그대로 받습니다.

Name	Type	Default	Description
`orientation`	`'vertical' \| 'horizontal' \| 'both'`	`'vertical'`	표시할 스크롤바의 방향입니다.
`type`	`'auto' \| 'always' \| 'scroll' \| 'hover'`	`'hover'`	스크롤바를 표시할 시점입니다. Radix 기본값은 hover입니다.
`scrollHideDelay`	`number`	`600`	스크롤이 멈춘 뒤 스크롤바를 숨기기까지의 시간(ms)입니다.
`viewportClassName`	`string`	-	스크롤 영역에 추가할 클래스입니다.
`viewportRef`	`Ref<HTMLDivElement>`	-	스크롤 영역 요소의 ref입니다. 스크롤 위치를 복원할 때 사용합니다.
`scrollbarClassName`	`string`	-	모든 스크롤바에 추가할 클래스입니다.

Examples

자주 쓰는 조합을 살펴보고, 필요한 예시의 코드를 펼쳐 확인하세요.

Always visible

스크롤 가능함을 항상 보여야 하는 표나 코드 영역에 씁니다.

행 1
행 2
행 3
행 4
행 5
행 6
행 7
행 8

import { type ScrollAreaProps, ScrollArea } from '@amineslab/ui'

import { type ReactNode, type CSSProperties, type ComponentPropsWithoutRef } from 'react'

import { cn } from '@amineslab/ui/utils'

function ExampleScrollListItem({ className, ...props }: ComponentPropsWithoutRef<'li'>) {
    return (<li {...props} className={cn('rounded-action px-2.5 py-2 text-body-2 hover:bg-interactive-item-hover', className)}/>);
}

interface ExampleScrollListProps extends Omit<ScrollAreaProps, 'children'> {
    children: ReactNode;
    listStyle?: CSSProperties;
}

function ExampleScrollList({ children, className, listStyle, ...props }: ExampleScrollListProps) {
    return (<ScrollArea {...props} className={cn('h-40 w-full max-w-80 rounded-section border border-elevation-700 bg-section-primary', className)}>
      <ul className="m-0 list-none p-2" style={listStyle}>
        {children}
      </ul>
    </ScrollArea>);
}

export default function ExamplePreview() {
  return ((<ExampleScrollList style={{ height: 120 }} type="always">
          {Array.from({ length: 8 }, (_, index) => (<ExampleScrollListItem key={`row-${index + 1}`}>행 {index + 1}</ExampleScrollListItem>))}
        </ExampleScrollList>))
}

사용 기준

권장하는 사용

높이나 너비가 고정된 목록, 패널, 사이드바에 사용합니다.

피해야 할 사용

페이지 전체 스크롤을 대체하지 마세요.
문서의 기본 스크롤은 브라우저에 맡깁니다.

접근성

화면에 맞는 이름을 제공하고, 키보드만으로 작업을 마칠 수 있는지 확인하세요.

Arrow keys: 스크롤 영역에 포커스가 있을 때 기본 스크롤 동작
Page Up 또는 Page Down: 페이지 단위로 스크롤