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.
It needs JavaScript, and it fails toward no mask
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>
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', 'both', 'start', 'end', 'auto' (measured — see above) |
scope |
string|null | null |
Scoped personalization key |
Accessibility
- Container has
tabindex="0"— keyboard users can focus the scroll area and scroll with arrow keys - Container has
role="region"witharia-label="Scrollable content"— screen readers announce it as a navigable region - Keyboard scrolling works via native browser behavior once the container is focused
- 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.
Keyboard Interaction
This component is a layout wrapper. Keyboard interaction is delegated to its children.
Design Tokens
The scroll area inherits scrollbar styles from the .wk-scrollbar CSS utility, which uses these tokens:
| Element | Token |
|---|---|
| Scrollbar track | --color-wk-bg-muted |
| Scrollbar thumb | --color-wk-text-subtle |
| Scrollbar thumb hover | --color-wk-text-muted |
| Font family | --font-wk-sans |
Edge-fade depth (fade) |
--fade-wk-size (default 2rem) |
Customization
Override defaults in config/wirekit.php:
'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