Scroll Area

Overview

Scroll Area keeps scrolling entirely native (the Viewport is a real overflow: auto element, so keyboard, wheel, touch, and trackpad all work unchanged) while layering a custom, consistently-styled scrollbar and thumb on top. It supports vertical and horizontal axes with a corner where they meet, and four visibility modes via Type.

Anatomy

@using Navius.Primitives.Components.ScrollArea

<NaviusScrollArea>
    <NaviusScrollAreaViewport>
        @* content *@
    </NaviusScrollAreaViewport>
    <NaviusScrollAreaScrollbar Orientation="vertical">
        <NaviusScrollAreaThumb />
    </NaviusScrollAreaScrollbar>
    <NaviusScrollAreaScrollbar Orientation="horizontal">
        <NaviusScrollAreaThumb />
    </NaviusScrollAreaScrollbar>
    <NaviusScrollAreaCorner />
</NaviusScrollArea>

Root

Prop	Type	Default	Description
`Type`	`string`	`"hover"`	Scrollbar visibility behavior: `auto` \| `always` \| `hover` \| `scroll`.
`Orientation`	`string`	`"vertical"`	Reflected as `data-orientation` for styling; does not gate which scrollbars render.
`ScrollHideDelay`	`int`	`600`	Milliseconds before hiding the scrollbar after scrolling/hover stops (`hover` / `scroll` types).
`Dir`	`string?`	-	Reading direction (`ltr` \| `rtl`); falls back to a cascaded direction provider.
`ChildContent`	`RenderFragment?`	-	The scroll area’s parts.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `div`.

Viewport

Prop	Type	Default	Description
`ChildContent`	`RenderFragment?`	-	The scrollable content.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `div`. Must be given `overflow: auto` (or orientation-specific overflow) and a bounded size.

Scrollbar

Prop	Type	Default	Description
`Orientation`	`string`	`"vertical"`	`"vertical"` or `"horizontal"`.
`ForceMount`	`bool`	`false`	Keeps the scrollbar in the DOM even when its axis has no overflow.
`ChildContent`	`RenderFragment?`	-	The Thumb.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `div`.

Thumb

Prop	Type	Default	Description
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `div`. Geometry (size/offset) is derived state; only forwarded attributes are configurable.

Corner

Prop	Type	Default	Description
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `div`.

Data attributes

Part	Attribute	Description
Root	`data-navius-scrollarea`	Present on the root.
Root	`data-orientation`	`"vertical"` \| `"horizontal"`
Root	`data-scrolling`	Present while actively scrolling.
Root	`data-has-overflow-x`	Present while the horizontal axis overflows.
Root	`data-has-overflow-y`	Present while the vertical axis overflows.
Viewport	`data-navius-scrollarea-viewport`	Present on the viewport.
Viewport	`data-navius-scrollarea-content`	Present on the inner content wrapper.
Scrollbar	`data-navius-scrollarea-scrollbar`	Present on the scrollbar.
Scrollbar	`data-orientation`	`"vertical"` \| `"horizontal"`
Scrollbar	`data-hovering`	Present while hovering the scroll area.
Scrollbar	`data-scrolling`	Present while actively scrolling.
Thumb	`data-navius-scrollarea-thumb`	Present on the thumb.
Thumb	`data-orientation`	`"vertical"` \| `"horizontal"`
Thumb	`data-scrolling`	Present while actively scrolling.
Corner	`data-navius-scrollarea-corner`	Present when both axes overflow.

Keyboard interactions

Key	Behavior
Arrow keys	Native browser scrolling when the Viewport (or a focusable child) is focused; not intercepted.
`Page Up` / `Page Down`	Native browser scrolling; not intercepted.
`Home` / `End`	Native browser scrolling; not intercepted.

ARIA mechanism

Scrolling stays native: the Viewport is a real overflow: auto element, so the platform’s keyboard, wheel, touch, and trackpad scrolling (and the browser’s own scroll semantics) work unchanged. The custom scrollbar is a presentational div with no role="scrollbar", deliberately, so it adds no redundant noise for assistive technology. Covered by the Playwright browser test suite.