ScrollArea

ScrollArea provides a container with custom styled scrollbars for consistent cross-browser appearance.

Import


import { ScrollArea } from '@tidbcloud/uikit'

Basic Usage


import { ScrollArea } from '@tidbcloud/uikit'
 
function Demo() {
  return (
    <ScrollArea h={250}>
      {/* Long content here */}
      <p>Content that exceeds the container height...</p>
    </ScrollArea>
  )
}

Horizontal Scrollbars


import { ScrollArea, Box } from '@tidbcloud/uikit'
 
function Demo() {
  return (
    <ScrollArea w={300} h={200}>
      <Box w={600}>{/* Wide content here */}</Box>
    </ScrollArea>
  )
}

Scrollbar Types

Control scrollbar behavior with the type prop:


import { ScrollArea } from '@tidbcloud/uikit'
 
function Demo() {
  return (
    <>
      {/* Scrollbars visible on hover (default) */}
      <ScrollArea h={200} type="hover">
        <div>Content...</div>
      </ScrollArea>
 
      {/* Scrollbars visible on scroll */}
      <ScrollArea h={200} type="scroll">
        <div>Content...</div>
      </ScrollArea>
 
      {/* Scrollbars always visible when content overflows */}
      <ScrollArea h={200} type="auto">
        <div>Content...</div>
      </ScrollArea>
 
      {/* Scrollbars always visible */}
      <ScrollArea h={200} type="always">
        <div>Content...</div>
      </ScrollArea>
 
      {/* Scrollbars always hidden */}
      <ScrollArea h={200} type="never">
        <div>Content...</div>
      </ScrollArea>
    </>
  )
}


import { useState } from 'react'
import { ScrollArea, Text, Code, Box } from '@tidbcloud/uikit'
 
function Demo() {
  const [scrollPosition, onScrollPositionChange] = useState({ x: 0, y: 0 })
 
  return (
    <>
      <ScrollArea w={300} h={200} onScrollPositionChange={onScrollPositionChange}>
        <Box w={600} h={400}>
          {/* Content */}
        </Box>
      </ScrollArea>
      <Text>
        Scroll position: <Code>{`{ x: ${scrollPosition.x}, y: ${scrollPosition.y} }`}</Code>
      </Text>
    </>
  )
}

Scroll to Position


import { useRef } from 'react'
import { ScrollArea, Button, Stack, Group } from '@tidbcloud/uikit'
 
function Demo() {
  const viewport = useRef<HTMLDivElement>(null)
 
  const scrollToBottom = () => viewport.current?.scrollTo({ top: viewport.current.scrollHeight, behavior: 'smooth' })
 
  const scrollToTop = () => viewport.current?.scrollTo({ top: 0, behavior: 'smooth' })
 
  return (
    <Stack align="center">
      <ScrollArea w={300} h={200} viewportRef={viewport}>
        {/* Long content */}
      </ScrollArea>
      <Group>
        <Button onClick={scrollToTop}>Scroll to top</Button>
        <Button onClick={scrollToBottom}>Scroll to bottom</Button>
      </Group>
    </Stack>
  )
}

ScrollArea.Autosize

Creates a scrollable container when content exceeds maxHeight:


import { ScrollArea } from '@tidbcloud/uikit'
 
function Demo() {
  return (
    <ScrollArea.Autosize mah={300} maw={400}>
      {/* Content that may or may not exceed max height */}
    </ScrollArea.Autosize>
  )
}

Key Props

Prop	Type	Default	Description
`type`	`'hover' \| 'scroll' \| 'auto' \| 'always' \| 'never'`	`'hover'`	Scrollbars behavior
`scrollbarSize`	`number \| string`	`'0.75rem'`	Scrollbar width/height
`offsetScrollbars`	`boolean \| 'x' \| 'y' \| 'present'`	-	Adds padding to offset scrollbars
`scrollHideDelay`	`number`	`1000`	Delay in ms to hide scrollbars for `hover`/`scroll` types
`scrollbars`	`'x' \| 'y' \| 'xy' \| false`	`'xy'`	Which scrollbars to render
`viewportRef`	`Ref<HTMLDivElement>`	-	Ref to the viewport element for programmatic scrolling
`onScrollPositionChange`	`(position: { x: number; y: number }) => void`	-	Called when scroll position changes
`onTopReached`	`() => void`	-	Called when scrolled to top
`onBottomReached`	`() => void`	-	Called when scrolled to bottom