navius

Components / Scroll Area

Scroll Area

Augments native scroll functionality for custom, cross-browser styling.

Tags

v1.2.0-beta.1
v1.2.0-beta.0
v1.1.5
v1.1.4
v1.1.3
v1.1.2
v1.1.1
v1.1.0
v1.0.9
v1.0.8
v1.0.7
v1.0.6
v1.0.5
v1.0.4
v1.0.3
v1.0.2
v1.0.1
v1.0.0
v0.9.0
v0.8.0
razor
<NaviusScrollArea Type="hover" class="relative h-60 w-64 overflow-hidden rounded-md border">
    <NaviusScrollAreaViewport class="h-full w-full">
        @* ... scrollable content ... *@
    </NaviusScrollAreaViewport>
    <NaviusScrollAreaScrollbar Orientation="vertical"
                               class="flex w-2.5 p-0.5 opacity-0 data-[hovering]:opacity-100 data-[scrolling]:opacity-100">
        <NaviusScrollAreaThumb class="flex-1 rounded-full bg-accent" />
    </NaviusScrollAreaScrollbar>
    <NaviusScrollAreaCorner class="bg-muted/40" />
</NaviusScrollArea>

Features

  • Scrolling stays native, so keyboard, wheel, touch, and trackpad all work for free.
  • Fully styleable custom scrollbar and thumb that sit consistently across browsers and platforms.
  • Supports both vertical and horizontal axes, with a corner where they meet.
  • Four visibility modes via Type: auto, always, hover, and scroll.
  • Right-to-left aware via Dir or a cascaded direction provider.

Installation

Install the brain, or copy just this primitive in with the CLI.

Terminal bash
navius add scroll-area

Anatomy

Import the parts and assemble them.

razor
@using Navius.Primitives.Components.ScrollArea

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

API Reference

Root

Contains all the parts of a scroll area. Owns the shared context and renders a div.

Prop Type Default
Type string "hover"
Orientation string "vertical"
ScrollHideDelay int 600
Dir string? -
ChildContent RenderFragment? -

Data attributes

Data attribute Values
[data-navius-scrollarea] Present on the root
[data-orientation] "vertical" | "horizontal"
[data-type] "auto" | "always" | "hover" | "scroll"

Viewport

The viewport area of the scroll area. This is the native overflow container; give it overflow and a bounded size. Renders a div.

Prop Type Default
ChildContent RenderFragment? -

Data attributes

Data attribute Values
[data-navius-scrollarea-viewport] Present on the viewport
[data-navius-scrollarea-content] Present on the inner content wrapper

Scrollbar

The vertical or horizontal scrollbar track for one axis. Renders a div.

Prop Type Default
Orientation string "vertical"
ForceMount bool false
ChildContent RenderFragment? -

Data attributes

Data attribute Values
[data-navius-scrollarea-scrollbar] Present on the scrollbar
[data-orientation] "vertical" | "horizontal"
[data-hovering] Present while hovering the scroll area
[data-scrolling] Present while actively scrolling

Thumb

The draggable handle inside a scrollbar; sizes and positions itself from scroll metrics. Renders a div.

Prop Type Default
…attributes IDictionary<string, object>? -

Data attributes

Data attribute Values
[data-navius-scrollarea-thumb] Present on the thumb
[data-orientation] "vertical" | "horizontal"
[data-scrolling] Present while actively scrolling

Corner

The square where the vertical and horizontal scrollbars meet. Renders only when both axes overflow. Renders a div.

Prop Type Default
…attributes IDictionary<string, object>? -

Data attributes

Data attribute Values
[data-navius-scrollarea-corner] Present when both axes overflow

Accessibility

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

Keyboard interactions

When the Viewport (or a focusable child) is focused, the standard browser scroll keys apply: Arrow keys, Page Up / Page Down, and Home / End. Navius does not intercept these.