rc-scroller

Native scroll region with an optional centered content layout and fullbleed track. The custom element host is the scrollport, so native scrolling APIs, events, restoration, and observers work without reaching into shadow DOM.

Package: @rcarls/rc-scroller
Element: <rc-scroller>
Native dependency: Custom element host is the native scrollport
State model: Declarative axis and layout
Main events: scroll (native)
Related: Theme previews

Installation

npm
Yarn

npm install @rcarls/rc-scroller

yarn add @rcarls/rc-scroller

import '@rcarls/rc-scroller/define';

Markup

<rc-scroller layout="content" role="region" aria-label="Recipes">
  <header data-rc-scroller-span="fullbleed">Recipes</header>
  <article>Apple pie</article>
</rc-scroller>

Give the host a definite block size, or place it in a layout that provides one, when it should scroll. axis accepts block (the default), inline, or both. The component does not add a landmark, accessible name, or tab stop; authors add those semantics only when the surrounding document needs them.

Live demo

Content layout

Set layout="content" to place direct children on a centered content track. The track uses --rc-scroller-content-padding-inline for its minimum gutters and --rc-scroller-content-max-inline-size for its maximum width. A direct child with data-rc-scroller-span="fullbleed" spans the entire available inline size while preserving source order.

Without layout="content", the component only establishes a native scrollport. It does not impose padding or child layout.

Scroll-boundary state

at-block-start, at-block-end, at-inline-start, and at-inline-end are reflected, read-only attributes: present when scrolled to (within a few pixels of) that edge on an enabled axis, or when that axis isn't scrollable at all (nothing more to reveal counts as already at both of its edges). Style an edge affordance from outside the shadow root by targeting the attribute directly, for example an edge-fade mask on an inline scroller:

rc-scroller[axis='inline'] {
  mask-image: linear-gradient(
    to right,
    transparent,
    black 24px,
    black calc(100% - 24px),
    transparent
  );
}

rc-scroller[axis='inline'][at-inline-start] {
  mask-image: linear-gradient(to right, black calc(100% - 24px), transparent);
}

rc-scroller[axis='inline'][at-inline-end] {
  mask-image: linear-gradient(to right, transparent, black 24px);
}

The component only tracks and reflects this state: it makes no visual decision of its own about how, or whether, to show it.

API

Properties

Property	Markup	Type	Default	Description
`axis`	`axis`	`RCScrollerAxis`	`'block'`	Scroll axis.
`layout`	`layout`	`RCScrollerLayout`	`'none'`	Optional child layout.
`atBlockStart`	`at-block-start`	`boolean`	`true`	Reflected, computed. See the class doc comment.
`atBlockEnd`	`at-block-end`	`boolean`	`true`	Reflected, computed. See the class doc comment.
`atInlineStart`	`at-inline-start`	`boolean`	`true`	Reflected, computed. See the class doc comment.
`atInlineEnd`	`at-inline-end`	`boolean`	`true`	Reflected, computed. See the class doc comment.

Methods

No public methods are documented in the custom elements manifest.

Events

No custom events are documented in the custom elements manifest.

Slots

Name	Description
`(default)`	Scrollable content.

CSS Custom Properties

Property	Default	Description
`--rc-scroller-overscroll-behavior`	`contain`	Overscroll behavior on enabled axes.
`--rc-scroller-overflow-anchor`	`auto`	Browser scroll anchoring behavior.
`--rc-scroller-scrollbar-width`	`auto`	Scrollbar width.
`--rc-scroller-scrollbar-color`	`auto`	Scrollbar thumb and track colors.
`--rc-scroller-content-padding-inline`	`1rem`	Minimum inline gutter in content layout.
`--rc-scroller-content-max-inline-size`	`100%`	Maximum width of the content track.
`--rc-scroller-content-row-gap`	`0`	Gap between rows in content layout.

CSS Parts

Part	Description
`content`	Wrapper for the default slot and optional layout grid.

Installation​

Markup​

Live demo​

Content layout​

Scroll-boundary state​

API​