Scroll Area

A custom scrollable container with styled scrollbars that integrates with the design system.

Installation

npm install @morphos/layout

pnpm add @morphos/layout

yarn add @morphos/layout

bun add @morphos/layout

Import

import { ScrollArea, ScrollAreaViewport, ScrollAreaScrollbar, ScrollAreaThumb } from '@morphos/layout'

Usage

@Component()
class MyComponent extends StatefulComponent {
  @State() scrollArea = new ScrollArea({ type: 'hover' })

  render() {
    return (
      <ScrollArea scrollArea={this.scrollArea}>
        <ScrollAreaViewport scrollArea={this.scrollArea}>
          <p>Long content that overflows the container...</p>
          {/* more content */}
        </ScrollAreaViewport>
        <ScrollAreaScrollbar scrollArea={this.scrollArea} orientation="vertical">
          <ScrollAreaThumb scrollArea={this.scrollArea} orientation="vertical" />
        </ScrollAreaScrollbar>
      </ScrollArea>
    )
  }
}

Scrolling happens natively on ScrollAreaViewport — the native scrollbar is hidden with CSS, and ScrollAreaScrollbar/ScrollAreaThumb render an ARIA-described overlay driven by the real scroll metrics. The overlay is also interactive: clicking the track jumps to that position, and the thumb can be dragged, both calling back into ScrollArea to scroll the viewport.

Compound components

Component	Description
`ScrollArea`	Root container — tracks scroll metrics and whether the content overflows
`ScrollAreaViewport`	The actual scrollable element (`overflow: auto`) — reports scroll metrics to `ScrollArea`
`ScrollAreaScrollbar`	The scrollbar track (`role="scrollbar"`)
`ScrollAreaThumb`	The draggable thumb, sized/positioned from real scroll metrics via CSS custom properties

Props — ScrollArea

Prop	Type	Default	Description
`type`	`"auto" \| "always" \| "scroll" \| "hover" \| "hidden"`	`"hover"`	When scrollbars are visible. This is exposed as `data-type` for CSS to act on — `"hidden"` is expected to hide the custom scrollbar entirely via CSS while the viewport still scrolls natively.
`class`	`string`	—	CSS class
`id`	`string`	—	HTML id
`children`	`Children`	—	Content — typically a `ScrollAreaViewport` and one or more `ScrollAreaScrollbar`

Methods — ScrollArea

Method	Description
`scrollTo(position: { top?: number; left?: number })`	Imperatively scrolls the viewport to the given position, clamped to the valid scroll range. Used internally by `ScrollAreaScrollbar` (track click) and `ScrollAreaThumb` (drag), but can be called directly too
`_onScroll(el: HTMLElement)`	Internal — called by `ScrollAreaViewport` on mount and on every `scroll` event to update tracked metrics
`_registerViewport(el: HTMLElement \| null)`	Internal — called by `ScrollAreaViewport` on mount/unmount to register (or clear) the viewport element used by `scrollTo`

Props — ScrollAreaViewport

Prop	Type	Default	Description
`scrollArea`	`ScrollArea`	—	The `ScrollArea` state instance
`children`	`Children`	—	The scrollable content
`class`	`string`	—	CSS class
`id`	`string`	—	HTML id

Props — ScrollAreaScrollbar

Prop	Type	Default	Description
`scrollArea`	`ScrollArea`	—	The `ScrollArea` state instance
`orientation`	`"vertical" \| "horizontal"`	`"vertical"`	Scrollbar axis
`children`	`Children`	—	Typically a `ScrollAreaThumb`
`class`	`string`	—	CSS class
`id`	`string`	—	HTML id

Clicking the track (outside the thumb) jumps the scroll position to wherever was clicked, matching native scrollbar track-click behavior.

Props — ScrollAreaThumb

Prop	Type	Default	Description
`scrollArea`	`ScrollArea`	—	The `ScrollArea` state instance — used to size/position the thumb proportionally to the visible fraction of content. Optional — sizing math no-ops without it.
`orientation`	`"vertical" \| "horizontal"`	`"vertical"`	Which scroll axis to size/position against
`class`	`string`	—	CSS class
`id`	`string`	—	HTML id
`children`	`Children`	—	Accepted by the prop type but not rendered — `ScrollAreaThumb` has no content slot

`data-*` attributes

Attribute	Element	When present
`data-type`	ScrollArea	Always — reflects the `type` prop value
`data-scrollable`	ScrollArea	Content overflows the viewport on either axis
`data-orientation`	ScrollAreaScrollbar	Always — reflects the `orientation` prop

ScrollAreaThumb doesn't read data-* attributes for sizing — it sets the CSS custom properties --morphos-thumb-size and --morphos-thumb-offset directly on its own inline style, computed from the tracked scroll metrics.

Styling example

.morphos-scroll-area-viewport {
  scrollbar-width: none;
}

.morphos-scroll-area[data-type="hover"] .morphos-scroll-area-scrollbar {
  opacity: 0;
  transition: opacity var(--morphos-transition-medium);
}

.morphos-scroll-area[data-type="hover"]:hover .morphos-scroll-area-scrollbar {
  opacity: 1;
}

.morphos-scroll-area-scrollbar[data-orientation="vertical"] .morphos-scroll-area-thumb {
  top: var(--morphos-thumb-offset, 0%);
  height: var(--morphos-thumb-size, 100%);
}

Interactive example