Scroll area | Arcadia Design

src/parts/part-1.tsx

src/parts/part-2.tsx

src/parts/part-3.tsx

src/parts/part-4.tsx

src/parts/part-5.tsx

src/parts/part-6.tsx

src/parts/part-7.tsx

src/parts/part-8.tsx

src/parts/part-9.tsx

src/parts/part-10.tsx

src/parts/part-11.tsx

src/parts/part-12.tsx

src/parts/part-13.tsx

src/parts/part-14.tsx

src/parts/part-15.tsx

src/parts/part-16.tsx

src/parts/part-17.tsx

src/parts/part-18.tsx

src/parts/part-19.tsx

src/parts/part-20.tsx

src/parts/part-21.tsx

src/parts/part-22.tsx

src/parts/part-23.tsx

src/parts/part-24.tsx

import { ScrollArea } from "@arcadia/ui";

function Files() {
  const files = Array.from({ length: 24 }, (_, i) => `src/parts/part-${i + 1}.tsx`);
  return (
    <ScrollArea fade="y" className="cmp-scroller" rootStyle={cmp.scroller as never}>
      <div {...sx("cmp-scroller-content", cmp.scrollerContent)}>
        {files.map((f) => <div key={f}>{f}</div>)}
      </div>
    </ScrollArea>
  );
}

TSX

import { ScrollArea } from "@arcadia/ui";

<ScrollArea fade="y" style={{ maxHeight: "var(--media-max-height)" }}>
  {files.map((f) => <div key={f}>{f}</div>)}
</ScrollArea>

Size the root, with a height or a max-height, and the viewport fills it. Scrolling is native. The 4px steel scrollbar overlays the content, so it takes no width; it shows while the area is hovered or scrolling and fades 600ms after. The edge fades grow with the hidden distance, from 0 to 24px, so a list scrolled to the top has no fade there. Scroll the list above to watch both ends change.

A transcript passes viewportRef and contentRef to useStickToBottom and sets anchoring={false}, so the hook owns pinning to the newest message.

Scrolls the app starts

Reader scrolling is never smoothed or scripted.

springScroll(el, to) is a critically damped spring (ω 26, ζ 1): half-way in about 65ms, settled in about 300ms, with no overshoot. It re-aims every frame when to is a function, so a jump lands on a bottom that keeps growing; beyond 1.5 viewports it fast-forwards; and it stops the moment the reader touches anything, while a trackpad's momentum tail from before it started neither stops it nor fights it. useStickToBottom's jumpToBottom() runs on it and lands pinned. Under reduced motion it is one instant write.

useScrollKeys(ref) puts PageUp, PageDown, Home, End and Space on the spring while focus is in the scroller (or on the page, with whenBodyFocused); a press while it runs steps from its target, so holding PageDown never falls behind. revealInView(viewport, row) brings a row in by its nearest edge with two rows of margin, and does nothing when it is already in view.

Keys on the spring

Focus the list, then press PageDown, End or Home.

01 src/parts/part-1.tsx

02 src/parts/part-2.tsx

03 src/parts/part-3.tsx

04 src/parts/part-4.tsx

05 src/parts/part-5.tsx

06 src/parts/part-6.tsx

07 src/parts/part-7.tsx

08 src/parts/part-8.tsx

09 src/parts/part-9.tsx

10 src/parts/part-10.tsx

11 src/parts/part-11.tsx

12 src/parts/part-12.tsx

13 src/parts/part-13.tsx

14 src/parts/part-14.tsx

15 src/parts/part-15.tsx

16 src/parts/part-16.tsx

17 src/parts/part-17.tsx

18 src/parts/part-18.tsx

19 src/parts/part-19.tsx

20 src/parts/part-20.tsx

21 src/parts/part-21.tsx

22 src/parts/part-22.tsx

23 src/parts/part-23.tsx

24 src/parts/part-24.tsx

25 src/parts/part-25.tsx

26 src/parts/part-26.tsx

27 src/parts/part-27.tsx

28 src/parts/part-28.tsx

29 src/parts/part-29.tsx

30 src/parts/part-30.tsx

31 src/parts/part-31.tsx

32 src/parts/part-32.tsx

33 src/parts/part-33.tsx

34 src/parts/part-34.tsx

35 src/parts/part-35.tsx

36 src/parts/part-36.tsx

37 src/parts/part-37.tsx

38 src/parts/part-38.tsx

39 src/parts/part-39.tsx

40 src/parts/part-40.tsx

41 src/parts/part-41.tsx

42 src/parts/part-42.tsx

43 src/parts/part-43.tsx

44 src/parts/part-44.tsx

45 src/parts/part-45.tsx

46 src/parts/part-46.tsx

47 src/parts/part-47.tsx

48 src/parts/part-48.tsx

49 src/parts/part-49.tsx

50 src/parts/part-50.tsx

51 src/parts/part-51.tsx

52 src/parts/part-52.tsx

53 src/parts/part-53.tsx

54 src/parts/part-54.tsx

55 src/parts/part-55.tsx

56 src/parts/part-56.tsx

57 src/parts/part-57.tsx

58 src/parts/part-58.tsx

59 src/parts/part-59.tsx

60 src/parts/part-60.tsx

61 src/parts/part-61.tsx

62 src/parts/part-62.tsx

63 src/parts/part-63.tsx

64 src/parts/part-64.tsx

65 src/parts/part-65.tsx

66 src/parts/part-66.tsx

67 src/parts/part-67.tsx

68 src/parts/part-68.tsx

69 src/parts/part-69.tsx

70 src/parts/part-70.tsx

71 src/parts/part-71.tsx

72 src/parts/part-72.tsx

73 src/parts/part-73.tsx

74 src/parts/part-74.tsx

75 src/parts/part-75.tsx

76 src/parts/part-76.tsx

77 src/parts/part-77.tsx

78 src/parts/part-78.tsx

79 src/parts/part-79.tsx

80 src/parts/part-80.tsx

import { useRef } from "react";
import { ScrollArea, useScrollKeys } from "@arcadia/ui";

function KeysOnTheSpring() {
  const viewport = useRef<HTMLDivElement>(null);
  useScrollKeys(viewport);
  const lines = Array.from({ length: 80 }, (_, i) => `${String(i + 1).padStart(2, "0")}  src/parts/part-${i + 1}.tsx`);
  return (
    <ScrollArea fade="y" className="cmp-scroller" rootStyle={cmp.scroller as never} viewportRef={viewport} viewportProps={{ tabIndex: 0, "aria-label": "Files" }}>
      <div {...sx("cmp-scroller-content", cmp.scrollerContent)}>{lines.map((l) => <div key={l}>{l}</div>)}</div>
    </ScrollArea>
  );
}

Only a scroll the app starts moves on a spring: a jump to the latest message, PageUp, PageDown, Home and End in a scroller, revealing the active row.

Examples

Horizontal

orientation and fade per axis: long code lines, wide tables.

export const keys = (combo: string) => combo.split("+").map((k) => GLYPHS[k] ?? k.toUpperCase());

import { ScrollArea } from "@arcadia/ui";

function Horizontal() {
  const code = `export const keys = (combo: string) => combo.split("+").map((k) => GLYPHS[k] ?? k.toUpperCase());`;
  return (
    <ScrollArea orientation="horizontal" fade="x" className="cmp-code-line" rootStyle={cmp.codeLine as never}>
      {/* the old `.cmp-code-line > pre` rule never matched: the kit wraps content, so the pre stays bare */}
      <pre>{code}</pre>
    </ScrollArea>
  );
}

Under sticky chrome

A sticky label sets --scroll-fade-inset-top to its height: rows fade out at its lower edge instead of being cut by it.

Files 24

src/parts/part-1.tsx

src/parts/part-2.tsx

src/parts/part-3.tsx

src/parts/part-4.tsx

src/parts/part-5.tsx

src/parts/part-6.tsx

src/parts/part-7.tsx

src/parts/part-8.tsx

src/parts/part-9.tsx

src/parts/part-10.tsx

src/parts/part-11.tsx

src/parts/part-12.tsx

src/parts/part-13.tsx

src/parts/part-14.tsx

src/parts/part-15.tsx

src/parts/part-16.tsx

src/parts/part-17.tsx

src/parts/part-18.tsx

src/parts/part-19.tsx

src/parts/part-20.tsx

src/parts/part-21.tsx

src/parts/part-22.tsx

src/parts/part-23.tsx

src/parts/part-24.tsx

import { ScrollArea } from "@arcadia/ui";

function UnderStickyChrome() {
  const files = Array.from({ length: 24 }, (_, i) => `src/parts/part-${i + 1}.tsx`);
  return (
    <ScrollArea fade="y" className="cmp-scroller" rootStyle={[cmp.scroller, cmp.scrollerInset] as never}>
      <div {...sx("cmp-sticky-label", cmp.stickyLabel)}>Files 24</div>
      <div {...sx("cmp-scroller-content", cmp.scrollerContent)}>
        {files.map((f) => <div key={f}>{f}</div>)}
      </div>
    </ScrollArea>
  );
}

A see-through bar laid over the scroller also sets --scroll-fade-inset-alpha to 0, so no rows show through it.

rootStyle takes where the scroller sits, the longest edge fade, the chrome the top fade starts under and the overlay scrollbar's size and inset.

--scroll-fade-size: TokenRef<Space>Default var(--space-6); The longest edge fade (24).
--scrollbar-size: TokenRef<Measure>Default var(--scrollbar-size-visible); The overlay scrollbar's thickness.
--scrollbar-inset: TokenRef<Space>Default var(--space-0-5); The scrollbar's distance from the edges.
--scroll-radius: TokenRef<Radius> | Derived | "0px"Default 0px; The corner of the box it sits in: the bar's cap stays concentric with it (R4). Default 0px.
--scroll-fade-inset-top: TokenRef<Measure> | TokenRef<Control> | Derived | "0px"Default 0px; Chrome over the top edge: the top fade starts below it. Default 0px.
--scroll-fade-inset-bottom: TokenRef<Measure> | TokenRef<Control> | Derived | "0px"Default 0px; The same on the bottom edge (a floating button). Default 0px.
--scroll-fade-inset-alpha: "0" | "1"Default 1; Past an inset: 1 paints (a sticky label inside), 0 hides rows under see-through chrome. Default 1.
--scroll-padding-block: TokenRef<Space> | "0px"Default 0px; A row scrolled into view stops this far from the edges. Default 0px.
--scroll-padding-top: TokenRef<Measure> | Derived | "0px"Default var(--scroll-padding-block); The same at the top alone. Default --scroll-padding-block.
--scrollbar-offset-top: TokenRef<Measure> | Derived | "0px"Default 0px; Chrome over the top edge: the vertical bar starts this much lower. Default 0px.

The viewport is a normal scroller: wheel, touch and keyboard scrolling all work, and keyboard focus draws an inset ring on the root. Pass viewportProps for a role or a label, such as role="log" on a transcript, so the region is announced for what it is.

↓↑: Scroll a line
PageDownPageUp: Scroll a page
HomeEnd: Jump to the start or the end

ScrollArea

fade: "y" | "x" | "both" | "top" | "bottom" | "left" | "right" | falseDefault false; Mask the edges that have hidden content; the fade grows with the hidden distance (0 → 24 px).
orientation: "vertical" | "horizontal" | "both"Default "vertical"; Which axes scroll (and get an overlay scrollbar).
anchoring: booleanDefault true; false: overflow-anchor: none, for scrollers whose pinning useStickToBottom owns (the thread).
stickyBar: booleanDefault false; Horizontal: the bar sticks to the bottom of the scroller around it while the area shows (a long diff).
timeline: `--${string}`; Names the viewport's block scroll timeline, for chrome that follows the scroll.
viewportRef: Ref<HTMLDivElement>; The scrolling element (pass it to useStickToBottom).
contentRef: Ref<HTMLDivElement>; The content wrapper (the second useStickToBottom ref).
viewportProps: Omit<ComponentProps<"div">, "ref" | "children">; Extra props for the viewport, e.g. role="log", aria-label.
rootStyle: RootStyle<ScrollAreaKnobs>; Typed StyleX override: where the scroller sits (layout) and its knobs.
className: string; A product's hook class for its own rules (being retired: new code sets rootStyle).

Rest props go to <div> props.

omega: numberDefault 26; Natural frequency in rad/s.
onFrame: (top: number) => void; After every write, with the new scrollTop.
onEnd: (reason: SpringScrollEnd) => void; Once, with why it stopped.

whenBodyFocused: boolean; Also take the keys while nothing has focus (<body>): the app's main scroller.
end: () => void; End jumps to the bottom through this (a transcript's jumpToBottom(true), which re-pins).
onKey: () => void; Called before a key moves the scroller, so a stick-to-bottom hook reads it as the reader's.

Usage

Scrolls the app starts

Keys on the spring

Examples

Horizontal

Under sticky chrome

Customising

Accessibility

API reference

ScrollArea

springScroll() 3 props

useScrollKeys() 3 props