Layout

ScrollArea

Bounded scrolling container that constrains overflowing content within a max height or width while remaining keyboard-focusable.

import { ScrollArea } from '@lostgradient/cinder/scroll-area';
layoutoverflow
01

Overview

Bounded scrolling container that constrains overflowing content within a max height or width while remaining keyboard-focusable.

Usage

svelte 
<script lang="ts">
  import ScrollArea from '@lostgradient/cinder/scroll-area';

  const command =
    '$ bun run --filter=@lostgradient/cinder build && bun run --filter=@lostgradient/cinder test --coverage --reporter=verbose --bail';
</script>

<ScrollArea as="pre" direction="horizontal" maxWidth="32rem" label="Example command"
  ><code>{command}</code></ScrollArea
>

dragToScroll enables fine-pointer (mouse) click-and-drag scrolling with momentum, using the same physics as Carousel's mouse drag. Off by default, and not supported when direction="both". See scroll-area.a11y.md for the review.

Live preview
RunStatusDurationTriggered byCommitBranch
#4821passed4m 12savery9c1f8a2main
#4820failed3m 47sjordan2b4d701feat/scroll-area
#4819passed4m 03savery7e9a318main
#4818passed3m 58srenovate1a02fcechore/deps
#4817cancelled0m 41sjordan54bb6adfeat/grid-list
02

When to use

Use when
  • Containing a long list or large block of content inside a fixed-size region.
  • Preserving keyboard scrollability for overflow content in a card or surface.
Avoid when
  • Wrapping the entire page — let the document scroll natively.
  • Hiding overflow without scrollbars — use plain CSS overflow utilities instead.
03

Examples

Bidirectional scroll

A bounded viewport that scrolls both axes when the inner content exceeds both dimensions. Useful for wide tables or grids embedded in a fixed-size surface.

Horizontal code snippet

Horizontal scrolling for a long single-line code sample, rendered as a <pre> via the `as` prop so the region role is preserved alongside the semantic tag.

Themed scrollbar tokens

Overrides --cinder-scrollbar-thumb and --cinder-scrollbar-thumb-hover on a wrapping surface so the native scrollbar picks up brand colors without replacing it.

Vertical chat transcript

A vertical scroll region with a meaningful accessible name, so assistive technology treats it as a landmark via the derived role="region".

04

Props

Props for scroll-area
Name
Type
Default
Description
direction 'vertical' | 'horizontal' | 'both' 'vertical' Axis to allow scrolling on. Defaults to 'vertical'.
maxHeight text Maximum block size of the scroll viewport (any valid CSS length).
maxWidth text Maximum inline size of the scroll viewport (any valid CSS length).
label text Accessible name for the scroll region. When provided on neutral containers, the container also gets role="region" so assistive technology treats it as a landmark. Semantic tags keep their native roles. Provide this when the scroll area represents a meaningful section (a chat transcript, a code panel) — omit it for purely decorative scrolling chrome. This is the single source of truth for the accessible name; pass it through this prop rather than the raw aria-label HTML attribute so the landmark role and label stay coupled.
tabindex number 0 Override the default focus behavior. The component sets tabindex="0" by default so keyboard users can reach the viewport for arrow-key scrolling. Pass tabindex={-1} when the viewport should be programmatically focusable without entering the tab order.
as 'article''aside''div''li''main''nav''ol''pre'
2 more members 'section''ul'
 'div' Element tag to render. Defaults to 'div'.
dragToScroll boolean false Enables fine-pointer (mouse) click-and-drag scrolling, with momentum. Default false — drag-to-scroll on a text-bearing pane is a preference, not a default; keyboard scrolling (arrow keys, Page Up/Down, Home/End) is unaffected either way. Not supported when direction is 'both'.
scrollFadeVisible boolean false Show a scroll-driven edge fade on the trailing edge of direction ('vertical' fades the bottom; 'horizontal' fades the inline-end edge). Opt-in and presentation-only — never the sole signal that content scrolls; the native scrollbar this component always renders remains the authoritative affordance. Has no effect when direction is 'both' (there is no single trailing edge to fade on two independent axes at once). Defaults to false.
children required snippet Scrollable content.