본문으로 건너뛰기

ScrollArea

ScrollArea 컴포넌트는 제한된 공간 내에서 콘텐츠를 스크롤할 수 있게 해주며, 사용자 정의 스크롤바를 제공합니다. 기본 브라우저 스크롤바를 대체하여 더 일관되고 시각적으로 매력적인 UI를 구현할 수 있습니다. 기본적으로 얇은 보더와 미묘한 그림자가 적용되어 있어 콘텐츠 영역이 명확하게 구분됩니다.

기능​

  • 커스텀 스타일링 스크롤바
  • 세로/가로/양방향 스크롤 지원
  • 자동 숨김 기능
  • 다크 모드 지원
  • 접근성 고려
  • 기본 보더 및 그림자 스타일 적용
  • 프로그래매틱 스크롤 제어
  • 미니멀한 디자인 스타일

가져오기​

import { ScrollArea } from 'react-components-library';

기본 사용법​

태그

태그 1
태그 2
태그 3
태그 4
태그 5
태그 6
태그 7
태그 8
태그 9
태그 10
태그 11
태그 12
태그 13
태그 14
태그 15
태그 16
태그 17
태그 18
태그 19
태그 20
태그 21
태그 22
태그 23
태그 24
태그 25
태그 26
태그 27
태그 28
태그 29
태그 30
태그 31
태그 32
태그 33
태그 34
태그 35
태그 36
태그 37
태그 38
태그 39
태그 40
태그 41
태그 42
태그 43
태그 44
태그 45
태그 46
태그 47
태그 48
태그 49
태그 50
import { ScrollArea } from 'react-components-library';

function Demo() {
  return (
    <ScrollArea height={200} width={350}>
      <div className="p-4">
        <h4 className="mb-4 text-sm font-medium leading-none">태그</h4>
        {Array.from({ length: 50 }).map((_, i) => (
          <div key={i} className="text-sm" style={{ paddingTop: i > 0 ? '8px' : 0 }}>
            태그 {i + 1}
          </div>
        ))}
      </div>
    </ScrollArea>
  );
}

예제​

태그 목록 예제​

간결하고 깔끔한 태그 목록 UI를 구현합니다.

Tags

v1.2.0-beta.50
v1.2.0-beta.48
v1.2.0-beta.47
v1.2.0-beta.46
v1.2.0-beta.45
v1.2.0-beta.44
v1.2.0-beta.43
v1.2.0-beta.42
v1.2.0-beta.41
v1.2.0-beta.40
<ScrollArea 
  width="320px"
  height="400px"
  scrollbarSize={4}
  scrollbarRadius={4}
  thumbColor="rgba(0, 0, 0, 0.2)"
  thumbHoverColor="rgba(0, 0, 0, 0.3)"
  thumbDragColor="rgba(0, 0, 0, 0.4)"
  borderColor="rgba(229, 231, 235, 0.5)"
  shadowColor="rgba(0, 0, 0, 0.03)"
>
  <div>
    <h2 style={{ 
      fontSize: '1.75rem', 
      fontWeight: '600',
      margin: '0 0 1.5rem',
      padding: '0 0.5rem'
    }}>
      Tags
    </h2>
    <div className="tag-list">
      <div className="tag-item">v1.2.0-beta.50</div>
      <div className="tag-item">v1.2.0-beta.48</div>
      <div className="tag-item">v1.2.0-beta.47</div>
      <div className="tag-item">v1.2.0-beta.46</div>
      <div className="tag-item">v1.2.0-beta.45</div>
      <div className="tag-item">v1.2.0-beta.44</div>
      {/* 추가 태그 아이템 */}
    </div>
  </div>
</ScrollArea>
/* 태그 목록 스타일 */
.tag-list {
  display: flex;
  flex-direction: column;
  gap: 0.75rem;
}

.tag-item {
  padding: 0.75rem 1rem;
  border-radius: 6px;
  border-bottom: 1px solid var(--border-color);
  font-size: 1rem;
  color: #111827;
  transition: background-color 150ms ease;
}

.tag-item:hover {
  background-color: rgba(0, 0, 0, 0.02);
}

.tag-item:last-child {
  border-bottom: none;
}

가로 스크롤​

orientation 속성을 "horizontal"로 설정하여 가로 스크롤을 구현합니다.

항목 1
항목 2
항목 3
항목 4
항목 5
항목 6
항목 7
항목 8
항목 9
항목 10
항목 11
항목 12
항목 13
항목 14
항목 15
항목 16
항목 17
항목 18
항목 19
항목 20
<ScrollArea 
  orientation="horizontal" 
  width={350}
  height="auto"
>
  <div className="flex p-4">
    {Array.from({ length: 20 }).map((_, i) => (
      <div 
        key={i} 
        style={{ 
          width: '100px', 
          height: '100px', 
          flexShrink: 0,
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
          backgroundColor: i % 2 === 0 ? '#f4f4f5' : '#e4e4e7',
          border: '1px solid #e4e4e7',
          borderRadius: '4px',
          marginRight: '8px',
          fontWeight: 500,
        }}
      >
        항목 {i + 1}
      </div>
    ))}
  </div>
</ScrollArea>

양방향 스크롤​

orientation 속성을 "both"로 설정하면 세로와 가로 방향 모두 스크롤할 수 있습니다.

칼럼 1칼럼 2칼럼 3칼럼 4칼럼 5칼럼 6칼럼 7칼럼 8칼럼 9칼럼 10
셀 1-1셀 1-2셀 1-3셀 1-4셀 1-5셀 1-6셀 1-7셀 1-8셀 1-9셀 1-10
셀 2-1셀 2-2셀 2-3셀 2-4셀 2-5셀 2-6셀 2-7셀 2-8셀 2-9셀 2-10
셀 3-1셀 3-2셀 3-3셀 3-4셀 3-5셀 3-6셀 3-7셀 3-8셀 3-9셀 3-10
셀 4-1셀 4-2셀 4-3셀 4-4셀 4-5셀 4-6셀 4-7셀 4-8셀 4-9셀 4-10
셀 5-1셀 5-2셀 5-3셀 5-4셀 5-5셀 5-6셀 5-7셀 5-8셀 5-9셀 5-10
셀 6-1셀 6-2셀 6-3셀 6-4셀 6-5셀 6-6셀 6-7셀 6-8셀 6-9셀 6-10
셀 7-1셀 7-2셀 7-3셀 7-4셀 7-5셀 7-6셀 7-7셀 7-8셀 7-9셀 7-10
셀 8-1셀 8-2셀 8-3셀 8-4셀 8-5셀 8-6셀 8-7셀 8-8셀 8-9셀 8-10
셀 9-1셀 9-2셀 9-3셀 9-4셀 9-5셀 9-6셀 9-7셀 9-8셀 9-9셀 9-10
셀 10-1셀 10-2셀 10-3셀 10-4셀 10-5셀 10-6셀 10-7셀 10-8셀 10-9셀 10-10
셀 11-1셀 11-2셀 11-3셀 11-4셀 11-5셀 11-6셀 11-7셀 11-8셀 11-9셀 11-10
셀 12-1셀 12-2셀 12-3셀 12-4셀 12-5셀 12-6셀 12-7셀 12-8셀 12-9셀 12-10
셀 13-1셀 13-2셀 13-3셀 13-4셀 13-5셀 13-6셀 13-7셀 13-8셀 13-9셀 13-10
셀 14-1셀 14-2셀 14-3셀 14-4셀 14-5셀 14-6셀 14-7셀 14-8셀 14-9셀 14-10
셀 15-1셀 15-2셀 15-3셀 15-4셀 15-5셀 15-6셀 15-7셀 15-8셀 15-9셀 15-10
<ScrollArea 
  orientation="both" 
  height={300}
  width={400}
>
  <div style={{ width: '800px' }}>
    <table style={{ borderCollapse: 'collapse', width: '100%' }}>
      <thead>
        <tr>
          {Array.from({ length: 10 }).map((_, i) => (
            <th key={i}>칼럼 {i + 1}</th>
          ))}
        </tr>
      </thead>
      <tbody>
        {Array.from({ length: 15 }).map((_, rowIndex) => (
          <tr key={rowIndex}>
            {Array.from({ length: 10 }).map((_, colIndex) => (
              <td key={colIndex}>
                셀 {rowIndex + 1}-{colIndex + 1}
              </td>
            ))}
          </tr>
        ))}
      </tbody>
    </table>
  </div>
</ScrollArea>

스크롤바 항상 표시​

autoHide 속성을 false로 설정하면 스크롤바가 항상 표시됩니다.

항목 1
항목 2
항목 3
항목 4
항목 5
항목 6
항목 7
항목 8
항목 9
항목 10
항목 11
항목 12
항목 13
항목 14
항목 15
항목 16
항목 17
항목 18
항목 19
항목 20
항목 21
항목 22
항목 23
항목 24
항목 25
항목 26
항목 27
항목 28
항목 29
항목 30
<ScrollArea 
  autoHide={false}
  height={200}
  width={350}
>
  <div className="p-4">
    {/* 내용 */}
  </div>
</ScrollArea>

프로그래매틱 스크롤 제어​

ref를 사용하여 스크롤 위치를 프로그래매틱 방식으로 제어할 수 있습니다.

항목 1
항목 2
항목 3
항목 4
항목 5
항목 6
항목 7
항목 8
항목 9
항목 10
항목 11
항목 12
항목 13
항목 14
항목 15
항목 16
항목 17
항목 18
항목 19
항목 20
항목 21
항목 22
항목 23
항목 24
항목 25
항목 26
항목 27
항목 28
항목 29
항목 30
항목 31
항목 32
항목 33
항목 34
항목 35
항목 36
항목 37
항목 38
항목 39
항목 40
항목 41
항목 42
항목 43
항목 44
항목 45
항목 46
항목 47
항목 48
항목 49
항목 50
import { useRef } from 'react';
import { ScrollArea, ScrollAreaRef } from 'react-components-library';

function ScrollDemo() {
  const scrollAreaRef = useRef<ScrollAreaRef>(null);
  
  const handleScrollToTop = () => {
    scrollAreaRef.current?.scrollToTop();
  };
  
  const handleScrollToBottom = () => {
    scrollAreaRef.current?.scrollToBottom();
  };
  
  const handleScrollToPosition = () => {
    scrollAreaRef.current?.scrollTo({ top: 150 });
  };
  
  return (
    <div className="flex flex-col gap-2">
      <div className="flex gap-2">
        <button onClick={handleScrollToTop}>맨 위로</button>
        <button onClick={handleScrollToBottom}>맨 아래로</button>
        <button onClick={handleScrollToPosition}>중간 위치로</button>
      </div>
      <ScrollArea 
        ref={scrollAreaRef}
        height={200}
        width={350}
      >
        <div className="p-4">
          {/* 내용 */}
        </div>
      </ScrollArea>
    </div>
  );
}

API​

ScrollArea​

속성타입기본값설명
childrenReactNode필수스크롤 영역 내부에 들어갈 컨텐츠
orientation'vertical' | 'horizontal' | 'both''vertical'스크롤 방향
autoHidebooleantrue스크롤바 자동 숨김 여부
hideDelaynumber1000자동 숨김 지연 시간 (ms)
widthstring | number-스크롤 영역 너비
heightstring | number-스크롤 영역 높이
maxWidthstring | number-스크롤 영역 최대 너비
maxHeightstring | number-스크롤 영역 최대 높이
classNamestring-루트 요소에 적용할 CSS 클래스
styleCSSProperties-루트 요소에 적용할 인라인 스타일
scrollbarPosition'inside' | 'outside''inside'스크롤바 위치
scrollbarSizenumber6스크롤바 두께 (px)
scrollbarRadiusnumber9999스크롤바 둥글기 (px)
trackColorstring'transparent'스크롤바 트랙 색상
thumbColorstring'rgba(0, 0, 0, 0.15)'스크롤바 썸 색상
thumbHoverColorstring'rgba(0, 0, 0, 0.25)'스크롤바 호버 시 썸 색상
thumbDragColorstring'rgba(0, 0, 0, 0.35)'스크롤바 드래그 시 썸 색상
borderColorstring'rgba(229, 231, 235, 1)'보더 색상
shadowColorstring'rgba(0, 0, 0, 0.05)'그림자 색상
backgroundColorstring'#ffffff'배경 색상
textColorstring'inherit'텍스트 색상
disableAnimationbooleanfalse애니메이션 비활성화 여부
disableUserScrollbooleanfalse사용자 스크롤 비활성화 여부
disableShadowbooleanfalse그림자 비활성화 여부
scrollAnimationDurationnumber300프로그래매틱 스크롤 애니메이션 시간 (ms)
theme'light' | 'dark' | 'auto''auto'테마 모드
onScroll(position: { scrollTop: number; scrollLeft: number; }) => void-스크롤 이벤트 핸들러
onScrollEnd(position: { scrollTop: number; scrollLeft: number; }) => void-스크롤 완료 이벤트 핸들러

CSS 변수​

컴포넌트는 다음 CSS 변수를 사용하여 스타일을 커스터마이징할 수 있습니다:

변수기본값 (라이트 테마)기본값 (다크 테마)설명
--track-colortransparenttransparent스크롤바 트랙 색상
--thumb-colorrgba(0, 0, 0, 0.15)rgba(255, 255, 255, 0.1)스크롤바 썸 색상
--thumb-hover-colorrgba(0, 0, 0, 0.25)rgba(255, 255, 255, 0.15)스크롤바 호버 시 썸 색상
--thumb-drag-colorrgba(0, 0, 0, 0.35)rgba(255, 255, 255, 0.2)스크롤바 드래그 시 썸 색상
--scrollbar-size6px6px스크롤바 두께
--scrollbar-radius9999px9999px스크롤바 둥글기
--border-colorrgba(229, 231, 235, 1)rgba(55, 65, 81, 1)스크롤 영역 보더 색상
--shadow-colorrgba(0, 0, 0, 0.05)rgba(0, 0, 0, 0.2)스크롤 영역 그림자 색상

ScrollAreaRef​

메서드설명
scrollTo(options: ScrollToOptions)컨텐츠를 특정 위치로 스크롤
scrollIntoView(element: HTMLElement, options?: ScrollIntoViewOptions)특정 요소가 보이도록 스크롤
scrollToTop(options?: { behavior?: ScrollBehavior })맨 위로 스크롤
scrollToBottom(options?: { behavior?: ScrollBehavior })맨 아래로 스크롤
scrollToLeft(options?: { behavior?: ScrollBehavior })맨 왼쪽으로 스크롤
scrollToRight(options?: { behavior?: ScrollBehavior })맨 오른쪽으로 스크롤
viewportElement뷰포트 요소 참조

접근성​

ScrollArea 컴포넌트는 접근성을 고려하여 설계되었습니다:

키보드 접근성​

ScrollArea 컴포넌트는 키보드 사용자를 위한 기본 브라우저 스크롤 동작을 유지합니다:

  • Tab: 컴포넌트 내부의 포커스 가능한 요소로 이동
  • Arrow Keys: 콘텐츠 스크롤 (포커스가 컴포넌트 내부에 있을 때)
  • Page Up/Down: 페이지 단위로 스크롤
  • Home/End: 콘텐츠의 시작 또는 끝으로 스크롤

스크린 리더 지원​

ScrollArea는 스크린 리더 사용자가 스크롤 가능한 콘텐츠와 상호 작용할 수 있도록 적절한 ARIA 속성을 포함합니다.

모션 감소 선호 설정 지원​

prefers-reduced-motion 미디어 쿼리를 지원하여 사용자의 모션 감소 선호 설정을 존중합니다. 이 설정이 활성화된 경우 모든 애니메이션이 비활성화됩니다.