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
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
NameTypeDefaultDescription
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.