Scroll Area

LayoutSince 0.9.0

import { ScrollArea } from '@absoluteui/components/scroll-area';
import '@absoluteui/components/scroll-area/style.css';

Using Angular? See Scroll Area for Angular.

What it does

Enhances an element whose content can overflow. Scrolling stays native (wheel, touch, trackpad, scrollbar, keyboard); the edges fade where more content exists (a CSS mask, so no elements are added and any background works); and while the content overflows, the element is a named, keyboard-focusable region, so keyboard users can scroll it (WCAG 2.1.1). There are no custom-drawn scrollbars.

When to use

• A bounded panel with long content: release notes, a log, a terms box, a side list.
• A horizontal strip of cards or chips that scrolls sideways.

When not to use

• The whole page (let the document scroll).
• Large data sets: use Data Table or Data Grid (they virtualize).
• Content that should simply be shorter.

Examples

Bounded panel with long content

import { ScrollArea } from '@absoluteui/components/scroll-area';

const notes = document.createElement('div');
for (let i = 1; i <= 30; i++) {
  const item = document.createElement('p');
  item.textContent = `Release 1.${String(i)}: improvements and fixes.`;
  notes.append(item);
}
document.body.append(notes);
ScrollArea.enhance(notes, { label: 'Release notes', maxBlockSize: '12rem' });

Horizontal strip

import { ScrollArea } from '@absoluteui/components/scroll-area';
import { Badge } from '@absoluteui/components/badge';

const strip = document.createElement('div');
strip.style.display = 'flex';
strip.style.gap = '0.5rem';
for (const label of ['Design', 'Engineering', 'Finance', 'Legal', 'Marketing', 'Operations', 'People', 'Product', 'Sales', 'Support']) {
  const host = document.createElement('span');
  strip.append(host);
  Badge.create(host, { label, variant: 'outline' });
}
document.body.append(strip);
ScrollArea.enhance(strip, { label: 'Departments', orientation: 'horizontal' });

Usage

import { ScrollArea } from '@absoluteui/components/scroll-area';
import '@absoluteui/components/scroll-area/style.css';

const terms = document.querySelector<HTMLElement>('#terms');
if (terms) ScrollArea.enhance(terms, { label: 'Terms of service', maxBlockSize: '20rem' });

More usage

import { ScrollArea } from '@absoluteui/components/scroll-area';

const log = document.querySelector<HTMLElement>('#activity');
if (log) {
  const area = ScrollArea.enhance(log, { label: 'Activity', maxBlockSize: '16rem' });
  // After changing content deep inside a child, recompute the edges.
  area.refresh();
}

Anatomy

<div class="aui-scroll-area aui-scroll-area--{orientation} aui-scroll-area--shadows"
     [role="region" aria-label="Release notes" tabindex="0"]          (while overflowing)
     [data-aui-scroll-top] [data-aui-scroll-bottom] ...>               (edges with hidden content)
  ... the element's own content ...
</div>

API reference

Factory

ScrollArea.enhance(element: HTMLElement, options: ScrollAreaOptions): ScrollArea

Global configuration key: scrollArea (see Configuration).

Options

Option	Type	Default	Description
label	string		Accessible name of the region. Required.
orientation	'vertical' | 'horizontal' | 'both'	"vertical"	Scroll axis.
maxBlockSize	string		Maximum block size as a CSS length (sets –aui-scroll-area-max-block-size).
shadows	boolean	"true"	Fade the edges where more content exists. Globally configurable.

Properties

Property	Type	Description
element	HTMLElement	The enhanced element.
edges	ScrollAreaEdges	Edges with hidden content ({ top, bottom, left, right }).
overflowing	boolean	Whether the content overflows (the region is then focusable).
options	Readonly<ScrollAreaOptions>	Current options.

Methods

Method	Description
refresh(): void	Recompute the edges now.
update(options: Partial<ScrollAreaOptions>): void	Merge and apply options.
destroy(): void	Remove classes, data attributes, observers, and restore the element’s own attributes.

Content areas

Area	Description
content	The element’s own children; they stay in place.

CSS classes

All rules live in the aui.components cascade layer, so application styles override them without specificity battles.

Class	Purpose
aui-scroll-area	The enhanced element.
aui-scroll-area--vertical | --horizontal | --both	Scroll axis.
aui-scroll-area--shadows	Edge fades are on.
data-aui-scroll-top | -bottom | -left | -right	Present while content is hidden at that edge.

Design tokens

Tokens this stylesheet reads (verified in CI). Override them in a theme or with the Theme Designer.

--aui-color-focus-ring | --aui-focus-ring-offset | --aui-focus-ring-width | --aui-space-6

TypeScript definitions

type ScrollAreaOrientation = 'vertical' | 'horizontal' | 'both';
interface ScrollAreaConfig { shadows: boolean }
interface ScrollAreaOptions extends Partial<ScrollAreaConfig> {
  label: string;
  orientation?: ScrollAreaOrientation;
  maxBlockSize?: string;
}
interface ScrollAreaEdges { readonly top: boolean; readonly bottom: boolean; readonly left: boolean; readonly right: boolean }

Accessibility

Pattern: Scrollable region (WCAG 2.1.1): a scrollable element that holds no focusable content must itself be focusable and named; it is a region with aria-label while it overflows.

Keyboard

Key	Context	Action
Tab	Page	Moves to the region while its content overflows.
Arrow keys / Page Up / Page Down / Home / End / Space	Focused region	Scroll natively.

Roles

Element	Role
element	region while overflowing when it is a generic div or span; otherwise its own role (a list stays a list)

ARIA attributes

Attribute	Element	Value
aria-label	element	the label option, while overflowing
tabindex	element	0 while overflowing (an existing tabindex is kept)

Focus

Focusable only while there is something to scroll; the focus ring is drawn with the fades off.

WCAG 2.2 success criteria addressed

Criterion	Level	Note
1.3.1 Info and Relationships	A
2.1.1 Keyboard	A
2.4.7 Focus Visible	AA
4.1.2 Name, Role, Value	A

Automated test results: Accessibility and compliance.

Notes and known caveats

• The fades are a visual hint only; screen-reader users reach all content in reading order.
• No custom scrollbars: the platform scrollbar, including its high-contrast and accessibility settings, is kept.
• Manual screen-reader verification (NVDA, JAWS, VoiceOver) is pending.

Behavior

States

Overflowing or not; scrolled to the start, the middle, or the end; vertical, horizontal, or both; fades on or off.

State transitions

From	Trigger	To
not overflowing	content or size change	overflowing: region role, label, and tab stop added
overflowing	scroll	edge attributes follow the position (at most once per frame)
overflowing	content shrinks	not overflowing: the element’s own attributes restored

Accessibility notes

• The fades are a visual hint; screen-reader users reach all content in reading order.
• The platform scrollbar, with its accessibility settings, is kept.
• The fades turn off while the region has keyboard focus, so the focus ring is never clipped.
• The e2e axe run covers three themes; manual screen-reader verification is pending.

Responsive behavior

Takes the size its layout gives it; maxBlockSize caps the height.

Right-to-left

Horizontal fades follow the scroll position in right-to-left layouts, where content starts at the right edge.

Theming

The fades are a mask, so they work on any background color. They are off in forced-colors mode.

Global configuration

configureAbsoluteUI({ components: { scrollArea: { shadows: false } } });

Component configuration

The instance shadows overrides configuration; configuration changes re-render existing scroll areas.

Security

maxBlockSize accepts only plain CSS lengths and calc(), min(), max(), or clamp() expressions, and is set through the CSSOM.

Data handling

No persistence, network access, or telemetry.

Performance

Edge state updates at most once per animation frame while scrolling. Resize observers watch the element and its direct children; a mutation observer re-attaches them when children change.

Supported data scale

Any amount of content that the browser can render; use the data components for large data sets.

Edge cases

• A region that stops overflowing is no longer focusable; if it had focus, focus stays on it until the user moves on.
• Size changes deeper than the direct children are noticed when a direct child resizes; call refresh() after other changes.

Errors

Code	Category	Cause
SCROLL_AREA_HOST	configuration	The target is not an element.
SCROLL_AREA_OPTIONS	configuration	Blank label, an unknown orientation, or a maxBlockSize that is not a plain CSS length.
CFG_INVALID_VALUE / CFG_UNKNOWN_OPTION	configuration	Invalid or unknown configuration.

Invalid options throw before the element is modified.

Known limitations

• The fades also fade content at the edges; avoid placing controls right at the edge.
• Manual screen-reader verification is pending.

Unsupported scenarios

• Custom scrollbars.
• Virtualized content.