A focusable, named scroll region with theme-aware custom thumb and native scrolling behavior for long lists and documents.
Recent activity
Everything happening in your workspace
import { CheckCircle2, MessageSquare, UploadCloud } from "lucide-react";
import { ScrollArea } from "@/components/ballmac/scroll-area";
const entries = [
{
icon: UploadCloud,
title: "New files uploaded",
detail: "Design assets · 2 minutes ago",
},
{
icon: MessageSquare,
title: "Comment added",
detail: "Q3 product brief · 18 minutes ago",
},
{
icon: CheckCircle2,
title: "Review completed",
detail: "Release checklist · 1 hour ago",
},
{
icon: UploadCloud,
title: "Preview updated",
detail: "Launch page · 3 hours ago",
},
{
icon: MessageSquare,
title: "Feedback received",
detail: "Brand guide · Yesterday",
},
];
export default function ScrollAreaDemo() {
return (
<div className="w-full max-w-sm overflow-hidden rounded-xl border bg-card shadow-sm">
<div className="border-b px-4 py-3">
<p className="text-sm font-semibold">Recent activity</p>
<p className="text-xs text-muted-foreground">
Everything happening in your workspace
</p>
</div>
<ScrollArea label="Recent workspace activity" className="h-52">
<ul className="divide-y px-4">
{entries.map(({ icon: Icon, title, detail }) => (
<li key={title} className="flex items-start gap-3 py-3">
<span className="flex size-8 shrink-0 items-center justify-center rounded-lg bg-muted">
<Icon aria-hidden="true" className="size-4" />
</span>
<div className="min-w-0">
<p className="text-sm font-medium">{title}</p>
<p className="text-xs text-muted-foreground">{detail}</p>
</div>
</li>
))}
</ul>
</ScrollArea>
</div>
);
}Installation
The default, and what a Radix-style project installs.
$ pnpm dlx shadcn@latest add @ballmac/scroll-areaInstall the dependencies.
$ pnpm add radix-uiCopy the source into your project.
components/ballmac/scroll-area.tsx// Ballmac UI: Scroll Area. https://ui.ballmac.com/components/scroll-area "use client"; import * as React from "react"; import { ScrollArea as Primitive } from "radix-ui"; import { cn } from "@/lib/utils"; type ScrollAreaProps = React.ComponentProps<typeof Primitive.Root> & { /** Accessible name of the focusable reading region. */ label: string; }; function ScrollArea({ className, children, label, ...props }: ScrollAreaProps) { return ( <Primitive.Root data-slot="scroll-area" className={cn("relative overflow-hidden rounded-lg", className)} {...props} > <Primitive.Viewport data-slot="scroll-area-viewport" role="region" aria-label={label} tabIndex={0} className="size-full rounded-[inherit] outline-none focus-visible:ring-[3px] focus-visible:ring-inset focus-visible:ring-ring/50" > {children} </Primitive.Viewport> <ScrollBar /> <Primitive.Corner data-slot="scroll-area-corner" className="bg-muted" /> </Primitive.Root> ); } type ScrollBarProps = React.ComponentProps<typeof Primitive.Scrollbar>; function ScrollBar({ className, orientation = "vertical", ...props }: ScrollBarProps) { return ( <Primitive.Scrollbar data-slot="scroll-area-scrollbar" orientation={orientation} className={cn( "flex touch-none select-none p-0.5 transition-colors duration-150 motion-reduce:transition-none", orientation === "vertical" ? "h-full w-2.5 border-s border-s-transparent" : "h-2.5 flex-col border-t border-t-transparent", className, )} {...props} > <Primitive.Thumb data-slot="scroll-area-thumb" className="relative flex-1 rounded-full bg-border hover:bg-muted-foreground/50" /> </Primitive.Scrollbar> ); } export { ScrollArea, ScrollBar, type ScrollAreaProps, type ScrollBarProps };Update the import paths to match your project setup.
$ pnpm dlx shadcn@latest add https://ui.ballmac.com/r/base/scroll-area.jsonInstall the dependencies.
$ pnpm add @base-ui/react@^1.9.0Copy the source into your project.
components/ballmac/scroll-area.tsx// Ballmac UI: Scroll Area. https://ui.ballmac.com/components/scroll-area "use client"; import * as React from "react"; import { ScrollArea as Primitive } from "@base-ui/react/scroll-area"; import { cn } from "@/lib/utils"; type ScrollAreaType = "auto" | "always" | "scroll" | "hover"; const TypeContext = React.createContext<ScrollAreaType>("hover"); type ScrollAreaProps = Omit<React.ComponentProps<typeof Primitive.Root>, "className"> & { className?: string; /** Accessible name of the focusable reading region. */ label: string; /** When the scrollbars show: "hover" (default) while the pointer is over the area, "scroll" while scrolling, "auto" or "always" whenever there is something to scroll. */ type?: ScrollAreaType; }; function ScrollArea({ className, children, label, type = "hover", ...props }: ScrollAreaProps) { return ( <TypeContext.Provider value={type}> <Primitive.Root data-slot="scroll-area" className={cn("relative overflow-hidden rounded-lg", className)} {...props} > <Primitive.Viewport data-slot="scroll-area-viewport" role="region" aria-label={label} tabIndex={0} className="size-full rounded-[inherit] outline-none focus-visible:ring-[3px] focus-visible:ring-inset focus-visible:ring-ring/50" > <Primitive.Content>{children}</Primitive.Content> </Primitive.Viewport> <ScrollBar /> <Primitive.Corner data-slot="scroll-area-corner" className="bg-muted" /> </Primitive.Root> </TypeContext.Provider> ); } type ScrollBarProps = Omit<React.ComponentProps<typeof Primitive.Scrollbar>, "className"> & { className?: string }; function ScrollBar({ className, orientation = "vertical", ...props }: ScrollBarProps) { const type = React.useContext(TypeContext); return ( <Primitive.Scrollbar data-slot="scroll-area-scrollbar" orientation={orientation} className={cn( "flex touch-none select-none p-0.5 transition-[color,opacity] duration-150 motion-reduce:transition-none", type === "hover" && "opacity-0 data-hovering:opacity-100 data-scrolling:opacity-100", type === "scroll" && "opacity-0 data-scrolling:opacity-100", type === "always" && "opacity-100", orientation === "vertical" ? "h-full w-2.5 border-s border-s-transparent" : "h-2.5 flex-col border-t border-t-transparent", className, )} {...props} > <Primitive.Thumb data-slot="scroll-area-thumb" className="relative flex-1 rounded-full bg-border hover:bg-muted-foreground/50" /> </Primitive.Scrollbar> ); } export { ScrollArea, ScrollBar, type ScrollAreaProps, type ScrollAreaType, type ScrollBarProps };Update the import paths to match your project setup.
Usage
import { ScrollArea, ScrollBar } from "@/components/ballmac/scroll-area"The full example is in the Code tab above.
Examples
Horizontal gallery
Project stages
import { ScrollArea, ScrollBar } from "@/components/ballmac/scroll-area";
export default function ScrollAreaStates() {
return (
<div className="w-full max-w-xs">
<p className="mb-2 text-sm font-medium">Project stages</p>
<ScrollArea
label="Project stages"
type="always"
className="w-full rounded-lg border"
>
<div className="flex w-max gap-2 p-3">
{["Planning", "Design", "Build", "Review", "Launch"].map(
(stage, index) => (
<div
key={stage}
className="w-28 shrink-0 rounded-lg bg-muted p-3"
>
<p className="text-xs text-muted-foreground">0{index + 1}</p>
<p className="mt-1 text-sm font-medium">{stage}</p>
</div>
),
)}
</div>
<ScrollBar orientation="horizontal" />
</ScrollArea>
</div>
);
}API reference
| Prop | Type | Default |
|---|---|---|
label*Accessible name of the focusable reading region. | string | — |
Also accepts the standard attributes of its root element.
Accessibility
| Key | Action |
|---|---|
| Tab | Focuses the named scroll region |
| Arrow keys / Page Up / Page Down | Scrolls the focused region |
Quality scorecard
Every applicable check passes
Measured in Chromium 153.0.8010.12 on October 19, 2026, on version 1.0.0, across 2 examples.
Passed: Accessibility scan
No serious or critical issues in light and dark, on a phone and a desktop (axe-core 4.13.0, WCAG 2.1 AA and best-practice rules).
Passed: Small screens
No sideways scrolling at 360, 390 or 1280 px wide.
Passed: Reduced motion
No endless animation to begin with.
Passed: Right to left
Mirrors correctly in Arabic, Hebrew, Persian and Urdu layouts (0% of elements off the mirror, limit 15%).
Passed: Clean console
No console errors or React hydration errors while loading.
Passed: Keyboard
2 tab stops, each showing a visible change when it takes focus. 2 documented keys.
Not applicable: Loading, empty and error
Does not show data or take submissions.
Passed: Automated tests
Covered by scroll-area.test.tsx.
For information: Footprint
0.7 KB of source (gzip) in 1 file. Installs radix-ui.
Automated checks find a subset of problems and do not replace testing with a screen reader and a keyboard in your own app. What they miss.
Use with AI
Constrains long content in an accessible keyboard-scrollable region without changing native scroll behavior. With the shadcn MCP server set up (guide), ask your agent:
Add the Ballmac UI Scroll Area (@ballmac/scroll-area) to this project with the shadcn MCP, then use it where it fits.
Use it for
- Activity feeds and long lists
- Constrained side panels
Not for
- Short content that can fit naturally
- The main page scroll
Registry JSON: https://ui.ballmac.com/r/scroll-area.json
Credits
Free to use in personal and commercial projects.
- npm
- radix-ui
- Registry
- shadcn/utils
Pairs well with
Activity Feed
A compact actor and action feed with timestamps and an empty state.
App Shell
The frame of an application page: skip link, sticky header, sidebar that becomes a sheet on small screens, main area, optional aside and footer.
Aspect Ratio
A CSS-native ratio frame that reserves space for media and safely handles invalid ratio values.
Bento Grid
A responsive bento layout of feature cards that span columns and rows. Each BentoCard has a background visual slot, icon, title and description, and a link that slides up on hover or focus.
Ballmac UI Pro
Need the whole screen, not one piece?
311 premium blocks (dashboards, settings, calendars, mail, shops, onboarding), a private shadcn registry and Figma tokens. Blocks that show data come with loading, empty and error states built in.
Not ready? Try three Pro blocks free
Leave your email and the blocks appear right here, ready to copy. Yours to use in any project.