Scroll AreaCopy Anchor Link

ScrollArea creates a styled, keyboard-focusable scroll viewport. children can be any React content: text, an article, cards, a table, a list, a canvas, or a custom layout. The component does not require the content to be an array or a particular HTML element.

InstallationCopy Anchor Link

import { ScrollArea } from '@mosmox/ui';
import '@mosmox/ui/styles.css';

Basic usageCopy Anchor Link

<ScrollArea aria-label="Recent activity" height={280}>
  <article>
    <h2>Article title</h2>
    <p>Any content that exceeds the viewport can be scrolled.</p>
  </article>
</ScrollArea>

The root container receives the supplied HTML attributes. The nested viewport is focusable with Tab by default and supports the browser's Arrow, Page Up/Down, Home, and End scrolling keys. Add aria-label or aria-labelledby when the surrounding UI does not already provide an accessible name.

OrientationCopy Anchor Link

<ScrollArea orientation="vertical" height={240}>{content}</ScrollArea>
<ScrollArea orientation="horizontal" width={480}>{wideContent}</ScrollArea>
<ScrollArea orientation="both" width={480} height={240}>{gridContent}</ScrollArea>

Scrollbar visibilityCopy Anchor Link

<ScrollArea scrollbar="auto">{content}</ScrollArea>
<ScrollArea scrollbar="always">{content}</ScrollArea>
<ScrollArea scrollbar="hover">{content}</ScrollArea>
<ScrollArea scrollbar="hidden">{content}</ScrollArea>

Use an alternative visual cue, such as fadeEdges, when choosing hidden.

Size and visual variantCopy Anchor Link

<ScrollArea size="sm" variant="soft">{content}</ScrollArea>
<ScrollArea size="lg" variant="bordered">{content}</ScrollArea>

size changes scrollbar thickness: sm is 6px, default is 8px, and lg is 12px. variant changes the root appearance:

• plain — default surface without an additional border or padding.
• bordered — adds a border and control radius.
• soft — adds a soft background, radius, and 8px padding.

Dimensions and edge fadesCopy Anchor Link

height, maxHeight, width, and maxWidth accept any corresponding React CSS value. Numbers are converted to pixels; strings can contain any valid CSS size such as %, rem, vh, min(), or calc().

<ScrollArea height={320} maxWidth="min(100%, 720px)" fadeEdges>
  {content}
</ScrollArea>

fadeEdges adds gradient overlays at the scrollable edges. It is false by default and follows the active orientation.

Events and edge detectionCopy Anchor Link

<ScrollArea
  height={320}
  scrollThreshold={12}
  onScroll={(event) => console.log(event.currentTarget.scrollTop)}
  onReachStart={() => console.log('reached start')}
  onReachEnd={() => loadMore()}
>
  {items}
</ScrollArea>

• onScroll receives the native React UIEvent<HTMLDivElement> from the internal viewport.
• onReachStart fires when scrolling enters the start edge.
• onReachEnd fires when scrolling enters the end edge.
• scrollThreshold is the edge tolerance in pixels and defaults to 2.

Edge callbacks fire once per arrival. They become eligible again after the viewport leaves that edge, so holding at the end does not repeatedly call onReachEnd. For horizontal, start/end are the left/right edges. For both, the callback fires only when both axes are at the corresponding edge.

Imperative controlsCopy Anchor Link

The forwarded ref exposes a ScrollAreaHandle for controlling the internal viewport:

import { useRef } from 'react';
import { ScrollArea, type ScrollAreaHandle } from '@mosmox/ui';

const ref = useRef<ScrollAreaHandle>(null);

<>
  <button onClick={() => ref.current?.scrollToTop()}>Top</button>
  <button onClick={() => ref.current?.scrollToBottom('smooth')}>Bottom</button>
  <button onClick={() => ref.current?.scrollTo({ top: 80, behavior: 'smooth' })}>
    Scroll to 80px
  </button>
  <ScrollArea ref={ref} height={300}>{content}</ScrollArea>
</>

The optional behavior is auto or smooth; the convenience methods default to smooth. viewportRef is separate from the forwarded component ref and gives direct access to the internal viewport element:

const viewportRef = useRef<HTMLDivElement>(null);
<ScrollArea viewportRef={viewportRef}>{content}</ScrollArea>

ConfigProvider defaultsCopy Anchor Link

The provider can set defaults for every ScrollArea. Instance props take precedence over provider values.

<ConfigProvider
  components={{
    scrollArea: {
      orientation: 'vertical',
      scrollbar: 'hover',
      size: 'sm',
      variant: 'soft',
      fadeEdges: true,
    },
  }}
>
  <ScrollArea height={240}>{content}</ScrollArea>
</ConfigProvider>

Supported defaults are orientation, scrollbar, size, variant, and fadeEdges. If neither the provider nor the instance supplies a value, the defaults are vertical, auto, default, plain, and false respectively.

APICopy Anchor Link

Accessibility and performanceCopy Anchor Link

The internal viewport is keyboard-focusable by default and shows a visible focus ring. Pass tabIndex={-1} when the viewport should not enter the normal tab order, or another value when your interaction model requires it. The component uses native scrolling and CSS overflow, avoids rendering a second copy of the content, and uses overscroll-behavior: contain to prevent scroll chaining to the page.