Skip to content
Browse documentation
whisk/ui

ScrollArea

Contain overflow while preserving an accessible scroll region.

Overview

ScrollArea creates a bounded, keyboard-reachable viewport with browser scrolling and Whisk/UI-managed visual scrollbar tracks. ScrollArea doesn't follow new content automatically; use ref and onScroll as shown below.

Use when

A bounded region must scroll independently from the page.

Use instead

Let the page scroll when the content does not need a separate viewport.

Usage

Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.

Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.

Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.

import { ScrollArea, Text } from "@smoothie-framework/whisk-react";

const content = Array(3).fill("Lorem ipsum dolor sit amet consectetur adipiscing elit.").join(" ");

<ScrollArea height={30} aria-label="Scrollable text" gutter="stable">
  <Text>{content}</Text>
</ScrollArea>

Examples

Variants

Use hover for tracks that appear on hover or while scrolling, and always when the scroll affordance should remain visible.

variant="hover"

Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.

Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.

Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.

variant="always"

Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.

Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.

Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.

import { ScrollArea, Stack, Text } from "@smoothie-framework/whisk-react";

const content = Array(3).fill("Lorem ipsum dolor sit amet consectetur adipiscing elit.").join(" ");

<Stack gap={3}>
  <Text size="sm" color="subtle">variant="hover"</Text>
  <ScrollArea height={30} variant="hover" aria-label="Hover scrollbar"><Text>{content}</Text></ScrollArea>
  <Text size="sm" color="subtle">variant="always"</Text>
  <ScrollArea height={30} variant="always" aria-label="Always visible scrollbar"><Text>{content}</Text></ScrollArea>
</Stack>

Sizes

size changes the visual scrollbar thickness; it does not change the viewport’s content typography. Extra-small and large show the available range.

xs

Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.

Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.

Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.

lg

Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.

Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.

Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.

import { ScrollArea, Stack, Text } from "@smoothie-framework/whisk-react";

const content = Array(3).fill("Lorem ipsum dolor sit amet consectetur adipiscing elit.").join(" ");

<Stack gap={2}>
  <Text size="sm" color="subtle">xs</Text>
  <ScrollArea size="xs" height={30} aria-label="Extra-small scrollbar"><Text>{content}</Text></ScrollArea>
  <Text size="sm" color="subtle">lg</Text>
  <ScrollArea size="lg" height={30} aria-label="Large scrollbar"><Text>{content}</Text></ScrollArea>
</Stack>

Horizontal scrolling

Give the viewport a bounded width and the child a wider minimum width when horizontal overflow is intentional.

Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.

import { Box, ScrollArea, Text } from "@smoothie-framework/whisk-react";

const content = Array(3).fill("Lorem ipsum dolor sit amet consectetur adipiscing elit.").join(" ");

<ScrollArea width={64} height={30} orientation="horizontal" aria-label="Horizontal text" gutter="stable">
  <Box minW="2xl">
    <Text>{content}</Text>
  </Box>
</ScrollArea>

Both directions

Use both only when content can legitimately exceed a bounded viewport in both dimensions.

Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.

import { Box, ScrollArea, Text } from "@smoothie-framework/whisk-react";

<ScrollArea width={64} height={30} orientation="both" aria-label="Canvas preview" variant="always">
  <Box minW="2xl" minH={64} padding={3} background="surface2" rounded="md">
    <Text>Lorem ipsum dolor sit amet consectetur adipiscing elit.</Text>
  </Box>
</ScrollArea>

Scroll to the latest message

Add a message to test the behavior. Follow new content only when the reader is already near the bottom; otherwise preserve their position.

Message 1 - 10:00:01

Message 2 - 10:00:02

Message 3 - 10:00:03

Message 4 - 10:00:04

Message 5 - 10:00:05

Message 6 - 10:00:06

Message 7 - 10:00:07

Message 8 - 10:00:08

Message 9 - 10:00:09

Message 10 - 10:00:10

import { useEffect, useRef, useState } from "react";
import { Box, Button, ScrollArea, Stack, Text } from "@smoothie-framework/whisk-react";

export function Transcript() {
  const viewport = useRef<HTMLDivElement | null>(null);
  const [messages, setMessages] = useState(Array.from({ length: 10 }, (_, index) => index + 1));
  const [followLatest, setFollowLatest] = useState(true);
  useEffect(() => {
    const node = viewport.current;
    if (followLatest && node) node.scrollTo({ top: node.scrollHeight });
  }, [messages.length, followLatest]);
  return (
    <Stack gap={2} align="start">
      <Button variant="secondary" onClick={() => setMessages([...messages, messages.length + 1])}>Add message</Button>
      <ScrollArea ref={viewport} width="full" height={30} role="log" aria-label="Transcript" onScroll={(event) => setFollowLatest(event.currentTarget.scrollHeight - event.currentTarget.scrollTop - event.currentTarget.clientHeight < 24)}>
        <Stack gap={2}>
          {messages.map((message) => (
            <Box key={message} padding={3} background="surface2" rounded="md">
              <Text>{"Message " + message + " - 10:00:" + String(message).padStart(2, "0")}</Text>
            </Box>
          ))}
        </Stack>
      </ScrollArea>
    </Stack>
  );
}

Hidden tracks

scrollbar="hidden" hides the visual tracks, not scrolling. This example uses a partially cut-off message to show that more content is available.

Message 1 - 10:00:01

Message 2 - 10:00:02

Message 3 - 10:00:03

import { Box, ScrollArea, Stack, Text } from "@smoothie-framework/whisk-react";

<ScrollArea height={30} scrollbar="hidden" aria-label="Recent messages">
  <Stack gap={2}>
    <Box padding={3} background="surface2" rounded="md"><Text>Message 1 - 10:00:01</Text></Box>
    <Box padding={3} background="surface2" rounded="md"><Text>Message 2 - 10:00:02</Text></Box>
    <Box padding={3} background="surface2" rounded="md"><Text>Message 3 - 10:00:03</Text></Box>
  </Stack>
</ScrollArea>

Props

Component props

PropTypeDefaultDescription
childrenRenderablenoneProvide the content inside the scrolling viewport.
orientationResponsive<vertical | horizontal | both>verticalChoose which axis can overflow.
variantResponsive<hover | always>hoverReveal visual scrollbar tracks while scrolling or hovering, or keep them visible.
sizeResponsive<xs | sm | md | lg>mdSet the visual scrollbar thickness preset.
scrollbarResponsive<auto | hidden>autoShow the managed visual tracks or hide them. This is not a browser scrollbar-width setting.
scrollbarWidthauto | thinautoChoose the browser scrollbar-width keyword; unlike size, it is not responsive and does not select Whisk’s visual-track thickness preset.
gutterResponsive<overlay | auto | stable | stable both-edges>overlayControl space reserved for scrollbars. Use stable when changing overflow must not move nearby content.

Shared props

PropSupportedNotes
as / asChildNoScrollArea owns its viewport structure.
Style propsYesStatic style props are applied to the scrolling viewport. See Style props.
className / styleYesApplied to the scrolling viewport.
refYesForwards to the scrolling viewport.
Native HTML attributesYesNative div attributes are forwarded to the scrolling viewport.

Accessibility

Give an independently scrollable region a nonempty aria-label or aria-labelledby. That makes the viewport a named region; descriptions alone do not name it. The viewport is keyboard-focusable by default, while visual tracks are hidden from assistive technology. Do not hide scrollbars without another clear cue that content continues, and retain normal page scrolling for ordinary document content.