ui/components/scroll-area

Scroll Area

Thin-scrollbar wrapper with vertical, horizontal, or both overflow directions.

Preview

tsx

1 import { ScrollArea } from "@/components/ui/scroll-area";2 3 export default function ScrollAreaDefault() {4   const items = Array.from({ length: 20 }, (_, i) => `Item ${i + 1}`);5   return (6     <ScrollArea aria-label="Item list" className="h-48 border border-border p-2">7       {items.map((item) => (8         <div key={item} className="py-1 px-2 text-sm text-foreground border-b border-border/30">9           {item}10         </div>11       ))}12     </ScrollArea>13   );14 }15

Installation

$pnpm exec dgadd add ui/scroll-area

[Installs to]src/components/ui/scroll-area[Item]ui/scroll-area

dgadd is not public on npm yet. Until the first release, pack @diffgazer/add from the repository and install that tarball into this app, which is what puts dgadd on pnpm exec.

UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS once packages are available.

Usage

tsx

1 import { ScrollArea } from "@/components/ui/scroll-area";2 3 export default function ScrollAreaDefault() {4   const items = Array.from({ length: 20 }, (_, i) => `Item ${i + 1}`);5   return (6     <ScrollArea aria-label="Item list" className="h-48 border border-border p-2">7       {items.map((item) => (8         <div key={item} className="py-1 px-2 text-sm text-foreground border-b border-border/30">9           {item}10         </div>11       ))}12     </ScrollArea>13   );14 }15

Examples

Horizontal

Preview

tsx

1 import { ScrollArea } from "@/components/ui/scroll-area";2 3 const HORIZONTAL_BLOCKS = Array.from({ length: 12 }, (_, index) => ({4   id: `h-block-${index + 1}`,5   label: `Block ${index + 1}`,6 }));7 8 export default function ScrollAreaHorizontal() {9   return (10     // The 1px inset keeps the scrollbar track off the container border so the11     // two hairlines never read as one doubled edge.12     <div className="w-full min-w-0 border border-border p-px">13       <ScrollArea aria-label="Horizontal strip" orientation="horizontal" className="p-2">14         <div className="flex gap-2 w-[800px]">15           {HORIZONTAL_BLOCKS.map((block) => (16             <div17               key={block.id}18               className="shrink-0 w-24 h-16 border border-border bg-secondary flex items-center justify-center text-xs text-muted-foreground"19             >20               {block.label}21             </div>22           ))}23         </div>24       </ScrollArea>25     </div>26   );27 }28

Both Directions

Preview

tsx

1 import { ScrollArea } from "@/components/ui/scroll-area";2 3 export default function ScrollAreaBoth() {4   return (5     // The 1px inset keeps both tracks off the container border, so the resting6     // horizontal thumb reads as its own edge instead of doubling the frame.7     <div className="w-full min-w-0 border border-border p-px">8       <ScrollArea aria-label="Two-axis demo" orientation="both" className="h-32 p-2">9         <div className="w-[600px]">10           {Array.from({ length: 15 }, (_, i) => (11             // biome-ignore lint/suspicious/noArrayIndexKey: fixed-length synthetic demo rows that never change order; the index is the stable identity.12             <div key={`b-line-${i}`} className="py-1 text-sm text-foreground whitespace-nowrap">13               {`Line ${i + 1}: ${"lorem ipsum dolor sit amet consectetur ".repeat(3)}`}14             </div>15           ))}16         </div>17       </ScrollArea>18     </div>19   );20 }21

Keyboard Region

Preview

tsx

1 import { ScrollArea } from "@/components/ui/scroll-area";2 3 const ROWS = Array.from({ length: 50 }, (_, index) => ({4   id: `commit-${index + 1}`,5   sha: (0x4a2f01 + index * 7919).toString(16).padStart(7, "0"),6   message: `commit ${index + 1}: refactor module ${String.fromCharCode(97 + (index % 26))}`,7 }));8 9 export default function ScrollAreaKeyboard() {10   return (11     <div className="flex flex-col gap-2">12       <p className="font-mono text-xs text-muted-foreground">13         Tab to focus the region, then Arrow / PageUp / PageDown / Home / End to scroll. The focus14         ring marks the region; the thumb proportion shows how far 50 rows run.15       </p>16       <ScrollArea aria-label="Commit log" className="h-48 border border-border p-2">17         {ROWS.map((row) => (18           <div key={row.id} className="flex gap-3 py-1 px-2 font-mono text-sm text-foreground">19             <span className="text-muted-foreground">{row.sha}</span>20             <span className="truncate">{row.message}</span>21           </div>22         ))}23       </ScrollArea>24     </div>25   );26 }27

Overlay

Preview

tsx

1 import { ScrollArea } from "@/components/ui/scroll-area";2 3 export default function ScrollAreaOverlay() {4   const items = Array.from({ length: 20 }, (_, i) => `Row ${i + 1}`);5   return (6     <ScrollArea overlay aria-label="Full-bleed rows" className="h-48 border border-border">7       {items.map((item) => (8         <div key={item} className="py-1 px-2 text-sm text-foreground border-b border-b-border/30">9           {item}10         </div>11       ))}12     </ScrollArea>13   );14 }15

API Reference

ScrollArea

Name	Type	Default	Description
orientation	"vertical" \| "horizontal" \| "both"	"vertical"	Axes that overflow. Other axes are clipped.
overlay	boolean	false	Hides the native scrollbar and floats a draggable thumb above the content, so rows can run border-to-border instead of stopping at a reserved track. Applies only with the vertical orientation — other orientations keep their native bar — and only on hover-capable devices; touch keeps the native indicator. Renders a zero-height rail as the container's first DOM child, ahead of children. The thumb hides when content fits, and it follows the same --scrollbar-thumb / --scrollbar-thumb-active tokens as the thin scrollbar.
keyboardScrollable	boolean	true	When true and the region has an accessible name (aria-label or aria-labelledby), wires Arrow/PageUp/PageDown/Home/End to scroll the container and gives it tabIndex={0}. role="region" follows the accessible name alone, so a named region keeps its role when this is false — hand key handling to a parent composite only when that parent also owns the tab stop.
children	ReactNode	—	Content rendered inside the scrollable container.

Accessibility

Keyboard Navigation

ScrollArea exposes role="region" whenever it has an accessible name (aria-label or aria-labelledby). When keyboardScrollable is also true, the named region becomes focusable and scrolls itself from keyboard events.

Key	Action
ArrowUp / ArrowDown	Scrolls vertical or both-axis regions by 40px.
ArrowLeft / ArrowRight	Scrolls horizontal or both-axis regions by 40px.
PageUp / PageDown	Scrolls vertical regions by 80% of height; horizontal-only regions scroll by 80% of width.
Home / End	Moves to the start or end of each enabled scroll axis.

Focusable region

Preview

tsx

1 import { ScrollArea } from "@/components/ui/scroll-area";2 3 const ROWS = Array.from({ length: 50 }, (_, index) => ({4   id: `commit-${index + 1}`,5   sha: (0x4a2f01 + index * 7919).toString(16).padStart(7, "0"),6   message: `commit ${index + 1}: refactor module ${String.fromCharCode(97 + (index % 26))}`,7 }));8 9 export default function ScrollAreaKeyboard() {10   return (11     <div className="flex flex-col gap-2">12       <p className="font-mono text-xs text-muted-foreground">13         Tab to focus the region, then Arrow / PageUp / PageDown / Home / End to scroll. The focus14         ring marks the region; the thumb proportion shows how far 50 rows run.15       </p>16       <ScrollArea aria-label="Commit log" className="h-48 border border-border p-2">17         {ROWS.map((row) => (18           <div key={row.id} className="flex gap-3 py-1 px-2 font-mono text-sm text-foreground">19             <span className="text-muted-foreground">{row.sha}</span>20             <span className="truncate">{row.message}</span>21           </div>22         ))}23       </ScrollArea>24     </div>25   );26 }27

Both directions

Preview

tsx

1 import { ScrollArea } from "@/components/ui/scroll-area";2 3 export default function ScrollAreaBoth() {4   return (5     // The 1px inset keeps both tracks off the container border, so the resting6     // horizontal thumb reads as its own edge instead of doubling the frame.7     <div className="w-full min-w-0 border border-border p-px">8       <ScrollArea aria-label="Two-axis demo" orientation="both" className="h-32 p-2">9         <div className="w-[600px]">10           {Array.from({ length: 15 }, (_, i) => (11             // biome-ignore lint/suspicious/noArrayIndexKey: fixed-length synthetic demo rows that never change order; the index is the stable identity.12             <div key={`b-line-${i}`} className="py-1 text-sm text-foreground whitespace-nowrap">13               {`Line ${i + 1}: ${"lorem ipsum dolor sit amet consectetur ".repeat(3)}`}14             </div>15           ))}16         </div>17       </ScrollArea>18     </div>19   );20 }21

Notes

Orientation

3 modes via orientation prop — vertical (default), horizontal, or both. The thin bar comes from the library's own unlayered .scrollbar-thin utility, which deliberately outranks Tailwind v4's same-named built-in. The overlay prop applies to the vertical mode only.

Wrapper Only

Without overlay, ScrollArea is a pure wrapper that adds thin scrollbar styling and renders no visual output of its own. With overlay it renders one zero-height rail as the container's first DOM child (ahead of children) carrying the floating thumb — account for it in position-keyed styling of direct children (first:, nth-child, space-y-*).

Resting Thumb

The thumb is visible at rest (foreground at 35%) and strengthens on hover or focus-within, so overflow is signalled before the pointer arrives. Chromium and WebKit get that resting thumb from the ::-webkit-scrollbar tree, and the standard scrollbar-width/scrollbar-color pair is confined to engines without that pseudo-element: declaring both on one element makes Chromium fall back to a platform overlay scrollbar that stays invisible until you scroll. Override --scrollbar-thumb and --scrollbar-thumb-active on the ScrollArea or any ancestor to retune both steps — the overlay mode's floating thumb consumes the same two tokens, so one retune moves both presentations. Give the scroll container at least 1px of inset from a surrounding border so the track and the border do not read as one doubled edge.

Source

Install via CLI: pnpm exec dgadd add ui/scroll-area.

Highlighted source loads after this disclosure opens. Browse the source repository.

Scroll Area

Installation

Usage

Examples

Horizontal

Both Directions

Keyboard Region

Overlay

API Reference

ScrollArea

Accessibility

Keyboard Navigation

Focusable region

Both directions

Notes

Orientation

Wrapper Only

Resting Thumb

Source

View component source (9 files)