Scroll area
A scroll area is a box with a size limit whose content scrolls. Keyboard users can reach and scroll it, and its scrollbar matches the theme.
1.4.0: Tables can pin their first column.
1.3.0: Date picker supports ranges.
1.2.0: Toasts stack and expand on hover.
1.1.0: Menus open submenus to the side.
1.0.0: First stable release.
<tk-scroll-area label="Release notes" fade style="max-block-size: 160px"> <p>1.4.0: Tables can pin their first column.</p> <p>1.3.0: Date picker supports ranges.</p> <p>1.2.0: Toasts stack and expand on hover.</p> <p>1.1.0: Menus open submenus to the side.</p> <p>1.0.0: First stable release.</p> </tk-scroll-area>
Anatomy
| Part | What it is |
|---|---|
tk-scroll-area |
the element; you give it the size |
| default slot | the content, anything |
scroll part |
the scrolling box; one Tab stop while the content overflows |
Size
The scroll area never picks a height. Limit it with height, max-height, or a flex or
grid track. Without a limit it grows with its content and never scrolls.
Axis
<tk-scroll-area label="Team" axis="horizontal">
<div style="display: flex; gap: var(--space-8); inline-size: max-content">
<tk-tag>Ada Lovelace</tk-tag><tk-tag>Grace Hopper</tk-tag><tk-tag>Alan Turing</tk-tag>
<tk-tag>Katherine Johnson</tk-tag><tk-tag>Edsger Dijkstra</tk-tag><tk-tag>Barbara Liskov</tk-tag>
</div>
</tk-scroll-area>vertical(default): scrolls up and down; content that's too wide is clipped.horizontal: scrolls sideways, for a strip of cards or a wide chart.both: scrolls in every direction, for a diagram or a wide log.
Options
fade: fades the content at an edge while there is more beyond it, and the fade goes away at the end. Use it where a cut-off edge could look like the end of the content. Set its depth with--tk-scroll-area-fade-size.gutter: reserves room for the scrollbar, so content doesn't shift when it starts to overflow. Systems with overlay scrollbars, such as macOS by default, reserve nothing.
The scrollbar is the browser's own, thin and colored from the theme. It looks slightly
different on each system. On a dark or tinted surface, set its color with
--tk-scroll-area-thumb-color.
When to use
- Use a scroll area for any region with a height limit whose content can overflow: a
changelog, a long list in a sidebar, a log, a media strip. Use it instead of a plain
overflow: autobox, which keyboard users can't scroll. - Don't wrap components that scroll themselves, such as
Table ,Data table , orCode block . You'd get two Tab stops. - Don't use it for the page; the page scrolls on its own.
- Avoid scroll areas inside scroll areas.
Do / Don't
| ✅ Do | ❌ Don't |
|---|---|
Limit the size yourself, such as with max-block-size |
Expect the scroll area to pick a height |
Set label on anything that can overflow |
Ship an unnamed scroll region |
Use fade where a cut edge could read as the end |
Add fade where rows or numbers already show there's more |
| Let tables and code blocks scroll themselves | Wrap them in a scroll area |
Related
Table ,Data table ,Code block : scroll the same way on their own.Skeleton : fill the area while content loads.
API
Attributes
| Attribute | Type | Default | What it does |
|---|---|---|---|
label |
string | the region's accessible name, used while the content overflows | |
axis |
vertical | horizontal | both |
vertical |
the direction that scrolls; the other is clipped |
gutter |
boolean | false |
reserves room for the scrollbar |
fade |
boolean | false |
fades the edges where more content lies beyond |
Slots
| Slot | Content |
|---|---|
| default | the scrolling content |
Events
No custom events.
CSS
| Custom property | Default | What it does |
|---|---|---|
--tk-scroll-area-thumb-color |
var(--border-default) |
the scrollbar thumb color |
--tk-scroll-area-fade-size |
var(--space-24) |
how deep the edge fade goes |
::part(scroll): the scrolling box, for padding or a size override.
Tokens
| Element | Token |
|---|---|
| scrollbar thumb | border/default; the track is transparent |
| focus ring | border/accent/focus, 2px, inside the edge |
| fade depth | space-24 |
The scroll area draws no background; the surface around it shows through. Values per
theme:
Accessibility
Built in:
- While the content overflows, the box is a Tab stop and, with a
label, a named region. When the content fits, both go away. - Arrow keys, Page Up, Page Down, Home, and End scroll the focused box, as in any browser.
- Without a
label, an overflowing box stays reachable but has no name. - The fade is hidden from screen readers; the scroll position says the same thing.
Your part:
- Set
labelon every scroll area that can overflow, such as "Release notes".
| Key | Action |
|---|---|
Tab |
moves focus to the scroll area while it overflows |
Up / Down, Left / Right |
scroll |
Page Up / Page Down |
scroll by a screen |
Home / End |
jump to the start or the end |