Skip to content

ScrollArea ​

A scrolling region that says where it is. While there is more below, the bottom edge fades; once it has moved off the top, the top edge does; and far enough down, a button eases in that takes it back to the start. Reach for it for any list or page taller than the box it lives in, where a plain scrollview would leave a person guessing whether the last row they see is the last row there is.

tsx
/** Thirty rows, more than the area has room for. */
const ROWS = Array.from({ length: 30 }, (_, at) => `Order ${1041 + at}`);

/**
 * A list taller than its box. Scroll it: the bottom edge fades while
 * there is more below, the top once it has moved off the first row, and
 * past 240 pixels a button eases in that takes it back to the top.
 */
export function OrderList(): UiChild {
  return (
    <ScrollArea width={percent(100)} height={320} backToTopAfter={240}>
      <column width={percent(100)}>
        {ROWS.map(row => (
          <row key={row} height={44} paddingX={16} y="center" borderColor="border">
            <text text={row} textStyle="body" />
          </row>
        ))}
      </column>
    </ScrollArea>
  );
}

Props ​

PropDefaultWhat it does
scrollYnoneWhere it is scrolled to, set at the start and whenever it changes
padding0Space around the content, inside the scroll bar, in pixels
paddingXpaddingSpace at the content's left and right
paddingYpaddingSpace at the content's top and bottom
fade24How tall each fade is, in pixels; 0 for none
fadeColor'background'The colour the fades blend into: what the area sits on
backToTopAfternoneShows the back-to-top button once scrolled this far, in pixels
backToTopLabel'Back to top'What the button is called, and what the default one says
backToTopGesso's buttonThe design's own drawing of the button, which the area makes pressable

Layout props place the area itself, as on every control; its content goes in as children and scrolls inside it.

Padding goes inside ​

padding pads the content, not the area, as padding on a scroller does on the web. Let the area run to the edges of what holds it and give it the padding the page would have had: the scroll bar is then at the page's edge and the rows keep their distance from the sides. A page that pads itself around the area puts the bar that far in from the edge, floating beside the content.

The fades ​

Each fade is a band of fadeColor at its edge that thins to the same colour at no opacity (a gradient stop's opacity), so it softens what passes under it and draws nothing over the space between rows. A ramp to transparent would pass through grey on the way, because a canvas blends a gradient's stops without premultiplying. The fades ease in and out with a transition timed fast, so they follow whatever the motion vocabulary says fast is.

Back to the top ​

The button is a small tonal Button unless backToTop gives an element of the design's own, which the area wraps in a box that takes the press, the focus and the name. Pressed, the area scrolls back over the vocabulary's slow on the clock where it is drawn (A clock for one part of the tree): on a settled clock it is back at once, which is what a design tool's board shows, and on a slowed one it takes as long as the clock says.

What this page was checked against ​

ScrollArea.spec.ts mounts it with gesso-testing and asserts that the bottom fades at first and the top once scrolled, that both fade into their own colour at no opacity, that the button appears past backToTopAfter and scrolls back part way on one frame and all the way in the end, and that a settled clock puts it at the top at once. The spec beside the example checks the example as written.