Scroll Area
A themed scrollable container that matches your WireKit design tokens. Wraps the built-in .wk-scrollbar CSS utility into a component with configurable orientation, max-height, and keyboard accessibility.
Basic Usage
Orientation
Horizontal
orientation="horizontal" scrolls the x-axis. Give the content an intrinsic
width wider than the area (here a width: max-content row of fixed-width tiles)
and it overflows sideways.
Both Directions
orientation="both" scrolls on both axes at once — for content that is wider
AND taller than the area (a large canvas, a wide table, a diagram).
Edge Fade
fade dissolves the content at the overflow edge, hinting there is more to
scroll. It masks the content itself (mask-image) rather than laying a
colored gradient on top — so it adapts to any background automatically, with
nothing to keep in sync with the surface color.
The fade follows the scroll axis: top/bottom for vertical (and both),
left/right for horizontal.
start and end mean the reading start and end, not the left and right. In a
right-to-left document — dir="rtl" anywhere above the component — a horizontal
fade="start" sits on the right edge and fade="end" on the left, which is where
those edges are for a reader of Arabic or Hebrew. Nothing to configure: the
component reads the document direction.
Worth knowing if you write CSS around it: there is no logical keyword for a
gradient, so this is a [dir="rtl"] override in the stylesheet rather than
something mask-image does on its own. fade="both" is symmetric and behaves
identically in either direction.
Use a single edge when only one direction can overflow — a log that grows
downward, for example, only needs the bottom (end) faded.
fade="auto" — only where there really is more
A named edge is unconditional CSS, and that is its limit as well as its virtue. It fades the top edge while you are already at the top, the bottom edge while you are at the bottom, and both edges on a scroll area whose content fits and cannot scroll at all — taking ink off text that is entirely visible, to signal something that is not true.
fade="auto" measures instead. The mask appears only on an edge the content
actually continues past: the bottom edge at the top of the area, the top edge at
the bottom, both in between, and nothing while everything fits.
It follows content that arrives later, which is the case worth having it for — a transcript that appends a message, a list a search filters down, a panel that opens. Nothing to call and nothing to refresh.
auto is the one value that does. Where scripts do not run, the area renders
with no fade at all and scrolls exactly as it would have — a missing hint
rather than dissolved text. Choose a named edge when you want the fade to be
guaranteed and can accept it being occasionally wrong; choose auto when you
would rather have nothing than the wrong hint.
Tune the depth with the --fade-wk-size token — globally in :root or per
instance:
{{-- 1. A deeper, softer fade on this one scroll area --}}
<x-wirekit::scroll-area fade="both" style="--fade-wk-size: 4rem;">
{{-- content --}}
</x-wirekit::scroll-area>
Max Height
Use the maxHeight prop for scroll areas with dynamic content:
<x-wirekit::scroll-area max-height="200px">
{{-- Long list of items --}}
@foreach($items as $item)
<div>{{ $item->name }}</div>
@endforeach
</x-wirekit::scroll-area>
Or use Tailwind classes directly:
<x-wirekit::scroll-area class="max-h-64">
{{-- Content --}}
</x-wirekit::scroll-area>
On paper the area grows to everything it holds, whichever way you bound it, because a printer cannot scroll, and an edge fade comes off with the bound. To give a box of your own the same, see data-wk-print-expand.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
orientation |
string | 'vertical' |
Scroll direction: 'vertical', 'horizontal', 'both' |
maxHeight |
string|null | null |
CSS max-height value (e.g. '200px', '50vh') |
fade |
bool|string | false |
Edge fade along the scroll axis: false / 'none', true / 'both', 'start', 'end', 'auto' (measured — see above) |
label |
string|null | null |
Accessible name for the region. Setting it also turns the area into a screen-reader landmark — see Accessibility |
scope |
string|null | null |
Scoped personalization key |
Accessibility
-
An
aria-labeloraria-labelledbyof yours names the area and makes it aregion, aslabeldoes -
Container has
tabindex="0"— keyboard users can focus the scroll area and scroll with arrow keys -
Keyboard scrolling works via native browser behavior once the container is focused
-
The landmark appears only when you name the region. With
labelset, the container getsrole="region"and thataria-label, so it shows up in a screen reader's landmark list. Without one it stays a plain focusable scroller. That is deliberate:role="region"plus a name is a landmark, and ten unnamed scroll areas on one page would be ten landmarks all announcing the same thing — which is what axe reports aslandmark-unique. Keyboard reachability (WCAG 2.1.1) never depended on the role, so nothing is lost by leaving it off. Name the region after its content:<x-wirekit::scroll-area label="Release notes" max-height="20rem"> {{-- … --}} </x-wirekit::scroll-area>An empty or whitespace-only
labelcounts as no name — arole="region"with an empty accessible name is not exposed as a landmark at all, so the component omits the role rather than shipping one nobody can identify. -
The edge fade never hides focus. When anything inside the area is focused (
:focus-within), the mask is dropped entirely — so a keyboard-focused child at an edge can never be faded out from under the user (WCAG 2.4.7 Focus Visible). The fade is static, so there is no motion to reduce. -
Give a control at the edge room for its focus ring. The area clips whatever reaches past its edges, and a focus ring reaches past the control it surrounds: a WireKit button's ring stands a little apart from the button and reaches
--ring-wk-widthplus--ring-wk-offsetbeyond it, 4px with the default tokens. A button or link flush against the area's edge loses that side of its ring. Give the area at least that much padding on the edges your content touches, as every example on this page does. Padding along the scroll axis moves a sticky header off the edge, so for a header that should rest at the top, pad the sides only:<x-wirekit::scroll-area max-height="18rem" label="Orders" style="padding-inline: 0.25rem;"> {{-- A page header whose action button sits at the right edge --}} </x-wirekit::scroll-area>
Keyboard Interaction
This component is a layout wrapper. Keyboard interaction is delegated to its children.
Design Tokens
These are the tokens the scroll area emits itself:
| Element | Token |
|---|---|
| Font family | --font-wk-sans |
Edge-fade depth (fade) |
--fade-wk-size (default 2rem) |
The scrollbar itself is styled by the .wk-scrollbar CSS utility, which the scroll area applies for you. Its thumb, hover and track colors and its width are separate tokens — see Scrollbar → Design Tokens for the list and the defaults.
Customization
Override defaults in config/:
'components' => [
// 1. Turn the edge fade on for every scroll area by default
'scroll-area' => ['fade' => 'both'],
],
Further Reading
- WCAG 2.1.1: Keyboard — scrollable regions must be keyboard-accessible
- MDN:
overflow - MDN: CSS Scrollbar Styling