Scroll Area

A scrolling region with scrollbars that look the same in every browser.

import * as stylex from "@stylexjs/stylex"
import { ScrollArea } from "@/components/ui/scroll-area"
import { VStack } from "@/components/ui/stack"
import { leading, radius, space, text } from "@/theme/tokens.stylex"

const styles = stylex.create({
  heading: { fontSize: text.sm, lineHeight: leading.sm, fontWeight: 500 },
  area: {
    height: "18rem",
    width: "12rem",
    borderRadius: radius.md,
    borderWidth: 1,
    borderStyle: "solid",
  },
  tag: {
    paddingBlockEnd: space.s2,
    borderBlockEndWidth: 1,
    borderBlockEndStyle: "solid",
    fontSize: text.sm,
    lineHeight: leading.sm,
  },
})

const tags = Array.from({ length: 50 }).map((_, i, a) => `v0.${a.length - i}.0`)

export default function ScrollAreaDemo() {
  return (
    <ScrollArea xstyle={styles.area}>
      <VStack padding={4} gap={4}>
        <h4 {...stylex.props(styles.heading)}>Releases</h4>
        <VStack gap={2}>
          {tags.map((tag) => (
            <div key={tag} {...stylex.props(styles.tag)}>
              {tag}
            </div>
          ))}
        </VStack>
      </VStack>
    </ScrollArea>
  )
}

Installation

pnpm dlx shadcn@latest add @arene/scroll-area

Needs the arene setup first.

Usage

import { ScrollArea, ScrollBar } from "@/components/ui/scroll-area"
<ScrollArea xstyle={styles.area}>Your scrollable content here.</ScrollArea>

Size and frame the root through xstyle. The viewport fills it and inherits its rounding, so a border and a radius on the root clip the content and shape the focus ring at once. ScrollArea renders the viewport, a vertical ScrollBar and the corner itself.

ScrollArea
└── ScrollBar

The scrolling element is a real scroll container with the native bar hidden, so the wheel, the keyboard and touch all work as they do on any overflow box. A scrollbar is mounted only while its axis overflows.

Horizontal

Add a ScrollBar with orientation="horizontal" for content wider than the frame. Give the content a max-content width or it wraps instead of overflowing.

import * as stylex from "@stylexjs/stylex"
import { ScrollArea, ScrollBar } from "@/components/ui/scroll-area"
import { HStack } from "@/components/ui/stack"
import { color, leading, radius, space, text, width } from "@/theme/tokens.stylex"

const styles = stylex.create({
  area: {
    width: "100%",
    maxWidth: width.sm,
    borderRadius: radius.md,
    borderWidth: 1,
    borderStyle: "solid",
    whiteSpace: "nowrap",
  },
  row: { width: "max-content" },
  figure: { flexShrink: 0 },
  frame: { overflow: "hidden", borderRadius: radius.md },
  image: { display: "block", aspectRatio: "3 / 4", objectFit: "cover" },
  caption: {
    paddingBlockStart: space.s2,
    fontSize: text.xs,
    lineHeight: leading.xs,
    color: color.mutedForeground,
  },
})

const photos = [
  {
    title: "Bicycle on a wet street",
    alt: "A bicycle leaning against a wall on a wet, narrow street",
    src: "https://images.unsplash.com/photo-1465869185982-5a1a7522cbcb?auto=format&fit=crop&w=300&q=80",
  },
  {
    title: "Stairs to a curved roof",
    alt: "A wide stairway rising to a curved concrete roof",
    src: "https://images.unsplash.com/photo-1548516173-3cabfa4607e9?auto=format&fit=crop&w=300&q=80",
  },
  {
    title: "Faceted glass facade",
    alt: "A building facade of angled glass and stone panels",
    src: "https://images.unsplash.com/photo-1494337480532-3725c85fd2ab?auto=format&fit=crop&w=300&q=80",
  },
]

export default function ScrollAreaHorizontal() {
  return (
    <ScrollArea xstyle={styles.area}>
      <HStack gap={4} padding={4} xstyle={styles.row}>
        {photos.map((photo) => (
          <figure key={photo.title} {...stylex.props(styles.figure)}>
            <div {...stylex.props(styles.frame)}>
              <img
                src={photo.src}
                alt={photo.alt}
                width={300}
                height={400}
                {...stylex.props(styles.image)}
              />
            </div>
            <figcaption {...stylex.props(styles.caption)}>{photo.title}</figcaption>
          </figure>
        ))}
      </HStack>
      <ScrollBar orientation="horizontal" />
    </ScrollArea>
  )
}

API reference

Pass render to replace a part's element or compose it with another component.

Every part wraps the Base UI ScrollArea part of the same name and accepts its props. See the Base UI reference. Both parts also take xstyle and className.

ScrollArea

PropTypeDefault
viewportPropsScrollAreaPrimitive.Viewport.Props & { xstyle?, className? }—
overflowEdgeThresholdnumber | Partial<{ xStart; xEnd; yStart; yEnd }>0
xstyleStyleXStyles—
classNamestring—

ScrollArea passes viewportProps to the element that scrolls. Put a ref there to scroll it from code, an onScroll to watch it, or className="scroll-fade-y" to fade its edges with the mask from interop.css.

ScrollBar

PropTypeDefault
orientation"vertical" | "horizontal""vertical"
keepMountedbooleanfalse

scrollAreaStyles

The style maps behind the component. Spread them onto any element.

KeyWhat it is
viewportFills the root, inherits its radius, plus the ring
scrollbarThe track: flex, 1px gutter, no touch or selection
orientationsvertical and horizontal track geometry
thumbThe rounded border-coloured grip

viewport is two styles, the scroller's own box and states.focusRing from theme/states.ts. The frame is on the root, so the viewport has no border of its own and only the ring's halo shows.

Data attributes

AttributeOnEffect
data-slot="scroll-area"the rootTargets the frame from a parent
data-slot="scroll-area-viewport"the scrollerTargets the element that scrolls
data-slot="scroll-area-content"the content boxBase UI watches its size to move the thumb
data-slot="scroll-area-scrollbar", data-orientationa trackTargets one bar; Base UI writes the orientation
data-slot="scroll-area-thumb"a gripTargets the thumb
data-slot="scroll-area-corner"the cornerPresent only while both bars are
data-has-overflow-x, data-has-overflow-yroot, viewport, tracksBase UI writes them while an axis overflows
data-overflow-x-start, -x-end, -y-start, -y-endroot, viewport, tracksBase UI writes them while content is hidden past that edge
data-scrolling, data-hoveringtracksBase UI writes them during a scroll and while hovered