Skip to content
Shaken UI
Sign in

Scroll Area

Save

A scrolling region built on Base UI Scroll Area with thin scrollbars that appear on hover or scroll and edges that fade where there is more content.

Category
Layout
Version
0.1.0
Frameworks
Next.js, Vite + React
Styling
Tailwind CSS v4

Preview

Scroll Area preview

Run log

18 lines

Artifacts from this run

Installation

npx @shakenui/cli add scroll-area

Review the plan first. A dry run lists every file and package without changing anything:

npx @shakenui/cli add scroll-area --dry-run

Usage

scroll-area-example.tsx
import { ScrollArea } from "@/components/shaken/ui/scroll-area";

const log: [time: string, level: "info" | "warn" | "error", message: string][] = [
  ["14:02:11", "info", "Cloning acme/billing-api at 4f2c91e"],
  ["14:02:13", "info", "Installing dependencies with pnpm 9.12"],
  ["14:02:41", "info", "Resolved 1,184 packages in 27.8s"],
  ["14:02:42", "info", "Running typecheck"],
  ["14:02:58", "warn", "src/invoices/export.ts: 'legacyFormat' is deprecated"],
  ["14:02:59", "info", "Typecheck passed with 1 warning"],
  ["14:03:00", "info", "Running 412 tests across 38 files"],
  ["14:03:19", "error", "invoices.test.ts > rounds tax per line item: expected 18.40, got 18.39"],
  ["14:03:20", "info", "Agent is reading src/invoices/tax.ts"],
  ["14:03:24", "info", "Proposed fix: round each line before summing"],
  ["14:03:25", "info", "Applying patch to src/invoices/tax.ts (+6 -3)"],
  ["14:03:26", "info", "Re-running invoices.test.ts"],
  ["14:03:31", "info", "38 of 38 test files passed"],
  ["14:03:32", "info", "Building production bundle"],
  ["14:03:58", "info", "Bundle size 412 kB, 3 kB smaller than main"],
  ["14:03:59", "info", "Uploading build artifacts"],
  ["14:04:06", "info", "Preview ready at billing-api-git-fix-tax.acme.dev"],
  ["14:04:07", "warn", "Waiting for approval to open a pull request"],
];

const levelTone = {
  info: "text-zinc-500",
  warn: "text-amber-600 dark:text-amber-400",
  error: "text-red-600 dark:text-red-400",
} as const;

const artifacts = [
  ["tax.ts", "Patch", "+6 −3"],
  ["invoices.test.ts", "Test run", "38 passed"],
  ["bundle-report.html", "Report", "412 kB"],
  ["preview.png", "Screenshot", "1440 × 900"],
  ["coverage.json", "Coverage", "91.4%"],
  ["changelog.md", "Notes", "12 lines"],
  ["pr-body.md", "Draft", "Pull request"],
];

export default function ScrollAreaExample() {
  return (
    <div className="flex w-full max-w-lg flex-col gap-6">
      <section className="overflow-hidden rounded-xl border border-zinc-950/10 bg-white shadow-[0_1px_2px_rgb(0_0_0/0.04)] dark:border-white/10 dark:bg-black dark:shadow-[inset_0_1px_0_rgb(255_255_255/0.06)]">
        <header className="flex items-center justify-between border-b border-zinc-950/[0.07] px-4 py-2.5 dark:border-white/[0.08]">
          <h3 id="run-log" className="m-0 text-sm font-semibold text-zinc-950 dark:text-white">
            Run log
          </h3>
          <span className="font-mono text-xs text-zinc-500 tabular-nums">{log.length} lines</span>
        </header>
        <ScrollArea className="h-56" aria-label="Run log output" contentClassName="py-2">
          <ol className="m-0 list-none p-0 font-mono text-xs leading-6">
            {log.map(([time, level, message], index) => (
              <li key={index} className="flex gap-3 px-4">
                <span className="shrink-0 text-zinc-400 tabular-nums dark:text-zinc-600">{time}</span>
                <span className={`w-10 shrink-0 ${levelTone[level]}`}>{level}</span>
                <span className="min-w-0 text-zinc-700 dark:text-zinc-300">{message}</span>
              </li>
            ))}
          </ol>
        </ScrollArea>
      </section>

      <section className="flex flex-col gap-2">
        <h3 className="m-0 text-xs font-medium text-zinc-500">Artifacts from this run</h3>
        <ScrollArea orientation="horizontal" aria-label="Artifacts from this run" contentClassName="pb-3">
          <ul className="m-0 flex w-max list-none gap-2 p-0">
            {artifacts.map(([name, kind, meta]) => (
              <li
                key={name}
                className="flex w-40 flex-col gap-1 rounded-lg border border-zinc-950/10 px-3 py-2.5 dark:border-white/10"
              >
                <span className="truncate font-mono text-xs text-zinc-950 dark:text-white">{name}</span>
                <span className="text-xs text-zinc-500">
                  {kind} · <span className="tabular-nums">{meta}</span>
                </span>
              </li>
            ))}
          </ul>
        </ScrollArea>
      </section>
    </div>
  );
}

API

PropTypeDefaultDescription
orientation"vertical" | "horizontal" | "both""vertical"Which axes scroll and get a scrollbar.
fadebooleantrueFades content out at edges that have more to scroll. Each fade grows with the scroll distance, so there is none at the very start.
fadeSizenumber24Maximum length of each edge fade, in pixels.
aria-labelstring—Names the scrolling region (role="region") when no heading labels it.
className / viewportClassName / contentClassNamestring—Classes for the root (set the height here), the scrolling viewport, and the content wrapper (for padding).
ScrollBar orientation"vertical" | "horizontal""vertical"The overlay scrollbar, exported for custom layouts.

Accessibility

  • Scrolling is native: wheel, touch, trackpad, Page Up, Page Down, and Space work as usual.
  • The viewport is focusable when it overflows, so keyboard users can scroll it with the arrow keys; its focus ring is drawn on the root so the edge fade cannot hide it.
  • With aria-label the viewport becomes a named region.
  • Scrollbars are visual helpers hidden at rest; they fade in within 100ms on hover or scroll and out over 300ms. With reduced motion they show and hide without transitions.
  • Edge fades are a mask tied directly to the scroll position, not an animation.

Files

Installed into src/components/shaken, or components/shaken when the project has no src directory.

  • src/components/shaken/ui/scroll-area.tsxscroll-area
  • npm packages: @base-ui/react@^1.9.0React and Tailwind CSS v4 required

Source

The exact source the CLI installs, from /r/items/react/scroll-area/0.1.0.json.

ui/scroll-area.tsxShow
ui/scroll-area.tsx
"use client";

import { ScrollArea as BaseScrollArea } from "@base-ui/react/scroll-area";
import type { CSSProperties } from "react";

function cx(...classes: (string | false | null | undefined)[]) {
  return classes.filter(Boolean).join(" ");
}

type ClassName<State> = string | ((state: State) => string | undefined) | undefined;

/** Prepends base classes while keeping Base UI's state-function form of className working. */
function withBase<State>(base: string, className: ClassName<State>) {
  return typeof className === "function" ? (state: State) => cx(base, className(state)) : cx(base, className);
}

export type ScrollAreaOrientation = "vertical" | "horizontal" | "both";

/**
 * Edge fades drawn with a mask on the viewport. Base UI exposes how far the content is scrolled
 * from each edge; each fade grows with that distance up to `--scroll-fade` (24px by default), so
 * it is absent at the very top and reaches full size after a short scroll. Nothing animates: the
 * fade follows the scroll position directly.
 */
const fadeY =
  "linear-gradient(to bottom, transparent, #000 min(var(--scroll-area-overflow-y-start, 0px), var(--scroll-fade, 24px)), #000 calc(100% - min(var(--scroll-area-overflow-y-end, 0px), var(--scroll-fade, 24px))), transparent)";
const fadeX =
  "linear-gradient(to right, transparent, #000 min(var(--scroll-area-overflow-x-start, 0px), var(--scroll-fade, 24px)), #000 calc(100% - min(var(--scroll-area-overflow-x-end, 0px), var(--scroll-fade, 24px))), transparent)";

const masks: Record<ScrollAreaOrientation, CSSProperties> = {
  vertical: { maskImage: fadeY, WebkitMaskImage: fadeY },
  horizontal: { maskImage: fadeX, WebkitMaskImage: fadeX },
  both: {
    maskImage: `${fadeY}, ${fadeX}`,
    WebkitMaskImage: `${fadeY}, ${fadeX}`,
    maskComposite: "intersect",
    WebkitMaskComposite: "source-in",
  },
};

export interface ScrollAreaProps extends Omit<BaseScrollArea.Root.Props, "className"> {
  /** Which axes scroll and get a scrollbar. */
  orientation?: ScrollAreaOrientation;
  /** Fades the content out at edges that have more to scroll. */
  fade?: boolean;
  /** Maximum length of each edge fade, in pixels. */
  fadeSize?: number;
  /** Classes for the root. Set the height (or max height) here. */
  className?: string;
  /** Classes for the scrolling viewport. */
  viewportClassName?: string;
  /** Classes for the content wrapper inside the viewport, for example padding. */
  contentClassName?: string;
  /** Accessible name for the scrollable region when its content has no heading to point at. */
  "aria-label"?: string;
}

/**
 * A scrolling region with thin scrollbars that appear while the pointer is over it or while it
 * scrolls, then fade away. Native scrolling, wheel, touch, and keyboard paging are unchanged;
 * the viewport is focusable so it can be scrolled with the arrow keys.
 */
export function ScrollArea({
  orientation = "vertical",
  fade = true,
  fadeSize = 24,
  className,
  viewportClassName,
  contentClassName,
  "aria-label": label,
  children,
  style,
  ...props
}: ScrollAreaProps) {
  const x = orientation !== "vertical";
  const y = orientation !== "horizontal";
  return (
    <BaseScrollArea.Root
      className={cx(
        "relative flex min-h-0 min-w-0 overflow-hidden rounded-[inherit]",
        // The focus ring belongs on the root; on the viewport the edge fade would mask it.
        "has-[[data-slot=scroll-viewport]:focus-visible]:outline-2 has-[[data-slot=scroll-viewport]:focus-visible]:outline-offset-2 has-[[data-slot=scroll-viewport]:focus-visible]:outline-sky-500",
        className,
      )}
      style={{ ...style, ["--scroll-fade" as string]: `${fadeSize}px` }}
      {...props}
    >
      <BaseScrollArea.Viewport
        data-slot="scroll-viewport"
        aria-label={label}
        role={label ? "region" : undefined}
        className={cx("h-full w-full flex-1 overscroll-contain rounded-[inherit] outline-none", viewportClassName)}
        style={fade ? masks[orientation] : undefined}
      >
        <BaseScrollArea.Content className={cx(x && "min-w-full", contentClassName)}>{children}</BaseScrollArea.Content>
      </BaseScrollArea.Viewport>
      {y ? <ScrollBar orientation="vertical" /> : null}
      {x ? <ScrollBar orientation="horizontal" /> : null}
      {x && y ? <BaseScrollArea.Corner /> : null}
    </BaseScrollArea.Root>
  );
}

export interface ScrollBarProps extends BaseScrollArea.Scrollbar.Props {}

/**
 * A thin overlay scrollbar. Hidden at rest; it fades in within 100ms when the pointer enters the
 * area or scrolling starts, and fades out more slowly once both stop. The thumb darkens while it
 * is hovered or dragged. Rendered automatically by `ScrollArea`; export for custom layouts.
 */
export function ScrollBar({ orientation = "vertical", className, ...props }: ScrollBarProps) {
  return (
    <BaseScrollArea.Scrollbar
      orientation={orientation}
      className={withBase(
        cx(
          "group/scrollbar absolute z-10 flex touch-none p-0.5 select-none",
          "data-[orientation=vertical]:top-0 data-[orientation=vertical]:right-0 data-[orientation=vertical]:bottom-(--scroll-area-corner-height) data-[orientation=vertical]:w-2.5",
          "data-[orientation=horizontal]:right-(--scroll-area-corner-width) data-[orientation=horizontal]:bottom-0 data-[orientation=horizontal]:left-0 data-[orientation=horizontal]:h-2.5 data-[orientation=horizontal]:flex-col",
          // Fade out over 300ms after a short pause; fade in quickly when needed.
          "opacity-0 transition-opacity delay-300 duration-300 ease-out motion-reduce:transition-none",
          "data-[hovering]:opacity-100 data-[hovering]:delay-0 data-[hovering]:duration-100",
          "data-[scrolling]:opacity-100 data-[scrolling]:delay-0 data-[scrolling]:duration-100",
        ),
        className,
      )}
      {...props}
    >
      <BaseScrollArea.Thumb
        className={cx(
          "rounded-full bg-zinc-950/25 dark:bg-white/25",
          "transition-colors duration-150 ease-out motion-reduce:transition-none",
          "group-hover/scrollbar:bg-zinc-950/45 active:bg-zinc-950/55 dark:group-hover/scrollbar:bg-white/45 dark:active:bg-white/55",
          "data-[orientation=vertical]:w-full data-[orientation=horizontal]:h-full",
        )}
      />
    </BaseScrollArea.Scrollbar>
  );
}