MATERIAL DESIGN 3 EXPRESSIVE

Scroll Area

Custom scrollbar component that provides a consistent, MD3 Expressive look and feel across all browsers.

The Scroll Area component augments native scroll functionality with a minimal, pill-shaped scrollbar that follows Material Design 3 Expressive guidelines. It ensures that scrollbars look and behave identically across different operating systems and browsers.

tag-1

tag-2

tag-3

tag-4

tag-5

tag-6

tag-7

tag-8

tag-9

tag-10

tag-11

tag-12

tag-13

tag-14

tag-15

tag-16

tag-17

tag-18

tag-19

tag-20

tag-21

tag-22

tag-23

tag-24

tag-25

tag-26

tag-27

tag-28

tag-29

tag-30

tag-31

tag-32

tag-33

tag-34

tag-35

tag-36

tag-37

tag-38

tag-39

tag-40

tag-41

tag-42

tag-43

tag-44

tag-45

tag-46

tag-47

tag-48

tag-49

tag-50

Default behaviour

type="scroll" (default) — scrollbar appears while scrolling.
Pill-shaped thumb with soft opacity.
Grows visual weight on hover / active for clarity.
Full keyboard navigation supported (Tab, ↑↓, PgUp/PgDn).

Loading demo...

Introduction

Native scrollbars often conflict with modern UI designs, appearing bulky or inconsistent across platforms. The MD3 Expressive Scroll Area solves this by providing a highly customizable, themeable scrollbar that only appears when needed. It is built on top of Radix UI's Scroll Area primitives, ensuring high performance and excellent accessibility.

Anatomy

Viewport: The visible area containing the scrollable content.
Scrollbar: The track and thumb used to navigate the content.
Thumb: The pill-shaped indicator that moves as the user scrolls.
Corner: The intersection where both horizontal and vertical scrollbars meet.

Variants

Orientations

Vertical (Default): For content that exceeds the height of its container.
Horizontal: For wide content like data tables or image galleries.
Both: Enables both vertical and horizontal scrolling with a dedicated corner element.

#	Name	Value	Type	Status	Date	Tags
1	Item 1	100	Alpha	Active	2025-01-01	tag-1
2	Item 2	127	Beta	Pending	2025-02-02	tag-2
3	Item 3	154	Gamma	Done	2025-03-03	tag-3
4	Item 4	181	Alpha	Active	2025-04-04	tag-4
5	Item 5	208	Beta	Pending	2025-05-05	tag-5
6	Item 6	235	Gamma	Done	2025-06-06	tag-6
7	Item 7	262	Alpha	Active	2025-07-07	tag-7
8	Item 8	289	Beta	Pending	2025-08-08	tag-8
9	Item 9	316	Gamma	Done	2025-09-09	tag-9
10	Item 10	343	Alpha	Active	2025-01-10	tag-10
11	Item 11	370	Beta	Pending	2025-02-11	tag-1
12	Item 12	397	Gamma	Done	2025-03-12	tag-2
13	Item 13	424	Alpha	Active	2025-04-13	tag-3
14	Item 14	451	Beta	Pending	2025-05-14	tag-4
15	Item 15	478	Gamma	Done	2025-06-15	tag-5
16	Item 16	505	Alpha	Active	2025-07-16	tag-6
17	Item 17	532	Beta	Pending	2025-08-17	tag-7
18	Item 18	559	Gamma	Done	2025-09-18	tag-8
19	Item 19	586	Alpha	Active	2025-01-19	tag-9
20	Item 20	613	Beta	Pending	2025-02-20	tag-10
21	Item 21	640	Gamma	Done	2025-03-21	tag-1
22	Item 22	667	Alpha	Active	2025-04-22	tag-2
23	Item 23	694	Beta	Pending	2025-05-23	tag-3
24	Item 24	721	Gamma	Done	2025-06-24	tag-4
25	Item 25	748	Alpha	Active	2025-07-25	tag-5
26	Item 26	775	Beta	Pending	2025-08-26	tag-6
27	Item 27	802	Gamma	Done	2025-09-27	tag-7
28	Item 28	829	Alpha	Active	2025-01-28	tag-8
29	Item 29	856	Beta	Pending	2025-02-29	tag-9
30	Item 30	883	Gamma	Done	2025-03-30	tag-10

Loading demo...

Features

Visibility Behaviors

Control when the scrollbar is displayed using the type prop:

Scroll (Default): Appears while scrolling and hides after a delay. Recommended for all devices and touch interactions.
Hover: Scrollbar appears only when hovering over the container (desktop-focused).
Always: Scrollbar is permanently visible.
None: Hides scrollbar UI completely while keeping native scrolling enabled.

type="hover"

Shows scrollbar only when the pointer enters the container.

tag-1

tag-2

tag-3

tag-4

tag-5

tag-6

tag-7

tag-8

tag-9

tag-10

tag-11

tag-12

tag-13

tag-14

tag-15

tag-16

tag-17

tag-18

tag-19

tag-20

hover

type="scroll"

Shows scrollbar only while actively scrolling.

tag-1

tag-2

tag-3

tag-4

tag-5

tag-6

tag-7

tag-8

tag-9

tag-10

tag-11

tag-12

tag-13

tag-14

tag-15

tag-16

tag-17

tag-18

tag-19

tag-20

scroll

type="always"

Scrollbar is always visible — best for accessibility.

tag-1

tag-2

tag-3

tag-4

tag-5

tag-6

tag-7

tag-8

tag-9

tag-10

tag-11

tag-12

tag-13

tag-14

tag-15

tag-16

tag-17

tag-18

tag-19

tag-20

always

type="none"

Scrollbar is hidden entirely (native scrolling still works).

tag-1

tag-2

tag-3

tag-4

tag-5

tag-6

tag-7

tag-8

tag-9

tag-10

tag-11

tag-12

tag-13

tag-14

tag-15

tag-16

tag-17

tag-18

tag-19

tag-20

none

Loading demo...

Custom Sizing & Colors

You can flexibly customize the thickness, colors, and border radius of the scrollbars using dedicated styling props:

scrollbarSize: Set scrollbar track thickness in pixels (e.g. 6 for slim, 14 for high visibility).
thumbClassName: Additional Tailwind CSS classes applied to the thumb element (overrides background colors, hover/active states, and border radius via tailwind-merge).
trackClassName: Tailwind CSS classes applied to the scrollbar track container.
cornerClassName: Tailwind CSS classes applied to the corner element when both orientations are active.
verticalScrollbarProps & horizontalScrollbarProps: Override styling and size individually per scroll axis.

Slim & Minimal6px

1. Material You Dynamic Color

2. Motion Spring Physics

3. Variable Typography

4. Expressive Elevation

5. Asymmetric Corner Shapes

6. Predictive Back Navigation

7. Floating Action Toolbars

8. Multi-Browse Carousel

9. Fading Blur Mask

10. Segmented Button Sets

11. Fluid Bottom Sheets

12. Contextual Search Dock

Primary Accent10px

1. Material You Dynamic Color

2. Motion Spring Physics

3. Variable Typography

4. Expressive Elevation

5. Asymmetric Corner Shapes

6. Predictive Back Navigation

7. Floating Action Toolbars

8. Multi-Browse Carousel

9. Fading Blur Mask

10. Segmented Button Sets

11. Fluid Bottom Sheets

12. Contextual Search Dock

Tertiary & Rounded-SM14px

1. Material You Dynamic Color

2. Motion Spring Physics

3. Variable Typography

4. Expressive Elevation

5. Asymmetric Corner Shapes

6. Predictive Back Navigation

7. Floating Action Toolbars

8. Multi-Browse Carousel

9. Fading Blur Mask

10. Segmented Button Sets

11. Fluid Bottom Sheets

12. Contextual Search Dock

Loading demo...

Expressive Styling

The scrollbar thumb is a pill-shaped element styled with Material Design 3 surface tokens (bg-m3-on-surface/25). It smoothly transitions to darker contrast on hover (hover:bg-m3-on-surface/40) and active drag (active:bg-m3-on-surface/55), while providing an accessible 44px touch target.

Usage

Basic Usage

import { ScrollArea } from "@bug-on/m3-expressive/layout";

<ScrollArea className="h-72 w-48 rounded-md border">
  <div className="p-4">
    <h4>Tags</h4>
    {tags.map((tag) => (
      <div key={tag} className="text-sm">
        {tag}
      </div>
    ))}
  </div>
</ScrollArea>

Custom Sizing and Colors

import { ScrollArea } from "@bug-on/m3-expressive/layout";

<ScrollArea
  scrollbarSize={8}
  thumbClassName="bg-m3-primary/60 hover:bg-m3-primary rounded-full"
  trackClassName="bg-m3-surface-container"
  className="h-64 w-80 rounded-m3-md border border-m3-outline-variant"
>
  <div className="p-4">
    {/* Scrollable content */}
  </div>
</ScrollArea>

Custom Scrollbar Composition

You can compose custom layouts directly using ScrollArea, ScrollAreaScrollbar, and ScrollAreaCorner:

import {
  ScrollArea,
  ScrollAreaScrollbar,
  ScrollAreaCorner,
} from "@bug-on/m3-expressive/layout";

<ScrollArea orientation="both" className="h-64 w-full">
  <div className="w-[1200px] h-[800px] p-4">Large canvas content</div>
  <ScrollAreaScrollbar orientation="vertical" scrollbarSize={8} />
  <ScrollAreaScrollbar orientation="horizontal" scrollbarSize={8} />
  <ScrollAreaCorner />
</ScrollArea>

Best Practices

Do

Use Scroll Area for containers with a fixed height where content may overflow.
Prefer type="scroll" for smooth, native-like mobile and desktop scrolling.
Use type="always" for critical scrollable areas (like sidebars or code blocks) where users need immediate visual orientation.
Use scrollbarSize and semantic MD3 tokens (bg-m3-primary, bg-m3-surface-container) to match the surrounding layout theme.
Set a clear max-height or height on the Scroll Area container.

Don't

Don't use Scroll Area for the entire page body; let the browser handle top-level scrolling.
Don't use orientation="both" if only one axis is likely to overflow.
Avoid nesting multiple Scroll Areas within each other, as it can be confusing for users to navigate.

Accessibility

Roles: Correctly implements ARIA roles for scroll containers and regions.
Keyboard: Supports standard keyboard navigation (Arrow keys, Page Up/Down, Home/End).
Touch: Provides native-feeling momentum scrolling on touch devices with accessible 44px min touch target on thumb.
Visibility: The scrollbar is a visual aid and doesn't replace native accessibility features.

API Reference

ScrollArea

Prop	Type	Default	Description
`type`	`"scroll" \| "hover" \| "always" \| "none"`	`"scroll"`	Visibility behavior of scrollbars.
`orientation`	`"vertical" \| "horizontal" \| "both"`	`"vertical"`	Scroll axis to render.
`scrollbarSize`	`number`	`10`	Thickness of scrollbar track in px (width for vertical, height for horizontal).
`thumbClassName`	`string`	—	Tailwind CSS classes for the thumb element (merges via `tailwind-merge`).
`trackClassName`	`string`	—	Tailwind CSS classes for the scrollbar track container.
`cornerClassName`	`string`	—	CSS classes for the corner element when both scrollbars are visible.
`verticalScrollbarProps`	`Omit<ScrollAreaScrollbarProps, "orientation">`	—	Props forwarded specifically to the vertical scrollbar.
`horizontalScrollbarProps`	`Omit<ScrollAreaScrollbarProps, "orientation">`	—	Props forwarded specifically to the horizontal scrollbar.
`thumbProps`	`ComponentPropsWithoutRef<typeof RadixScrollArea.Thumb>`	—	Extra props forwarded directly to inner thumb elements.
`scrollHideDelay`	`number`	`600`	Delay in ms before scrollbars hide when `type="scroll"` or `type="hover"`.
`viewportClassName`	`string`	—	Extra classes applied to the inner scrolling viewport element.
`viewportRef`	`React.Ref<HTMLDivElement>`	—	Ref to the scrolling viewport element.
`viewportProps`	`ComponentPropsWithoutRef<typeof RadixScrollArea.Viewport>`	—	Extra props applied to the inner viewport.
`className`	`string`	—	Custom classes applied to the root container.

ScrollAreaScrollbar

Standalone scrollbar component for custom composition.

Prop	Type	Default	Description
`orientation`	`"vertical" \| "horizontal"`	`"vertical"`	Scrollbar orientation (`"vertical"` or `"horizontal"`).
`scrollbarSize`	`number`	`10`	Thickness in pixels (`width` or `height`).
`thumbClassName`	`string`	—	Tailwind CSS classes for the thumb element.
`trackClassName`	`string`	—	Tailwind CSS classes for the track element.
`thumbRef`	`React.Ref<React.ElementRef<typeof RadixScrollArea.Thumb>>`	—	Ref forwarded directly to the inner thumb element.
`thumbProps`	`ComponentPropsWithoutRef<typeof RadixScrollArea.Thumb>`	—	Extra props forwarded to the thumb element.
`className`	`string`	—	Classes applied to the scrollbar container.

ScrollAreaCorner

Intersection corner component rendered when both scrollbars are active.

Prop	Type	Default	Description
`className`	`string`	—	Classes applied to the corner element (default: `bg-m3-surface-container`).