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
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"
variant="always"
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
lg
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.
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.
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.
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.
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
Shared props
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.