0
# Scrollbar System
1

2
Customizable scrollbar components that support multiple display modes, orientations, and accessibility features.
3

4
## Capabilities
5

6
### ScrollAreaScrollbar
7

8
The scrollbar component that handles scrolling interaction for both horizontal and vertical orientations.
9

10
```typescript { .api }
11
const ScrollAreaScrollbar: React.ForwardRefExoticComponent<
12
  ScrollAreaScrollbarProps & React.RefAttributes<ScrollAreaScrollbarElement>
13
>;
14

15
interface ScrollAreaScrollbarProps extends React.ComponentPropsWithoutRef<"div"> {
16
  /**
17
   * Scrollbar orientation
18
   * @default "vertical"
19
   */
20
  orientation?: "horizontal" | "vertical"; // default: "vertical"
21
  
22
  /**
23
   * Force mount the scrollbar regardless of visibility conditions
24
   * Useful for controlling animation with React animation libraries
25
   */
26
  forceMount?: true;
27
}
28

29
type ScrollAreaScrollbarElement = React.ComponentRef<"div">;
30
```
31

32
**Usage Examples:**
33

34
```typescript
35
import { ScrollAreaScrollbar } from "@radix-ui/react-scroll-area";
36

37
// Vertical scrollbar (default)
38
<ScrollAreaScrollbar>
39
  <ScrollAreaThumb />
40
</ScrollAreaScrollbar>
41

42
// Horizontal scrollbar
43
<ScrollAreaScrollbar orientation="horizontal">
44
  <ScrollAreaThumb />
45
</ScrollAreaScrollbar>
46

47
// Force mounted scrollbar for animation control
48
<ScrollAreaScrollbar forceMount>
49
  <ScrollAreaThumb />
50
</ScrollAreaScrollbar>
51
```
52

53
### ScrollAreaThumb
54

55
The draggable handle component within scrollbars that represents the current scroll position.
56

57
```typescript { .api }
58
const ScrollAreaThumb: React.ForwardRefExoticComponent<
59
  ScrollAreaThumbProps & React.RefAttributes<ScrollAreaThumbElement>
60
>;
61

62
interface ScrollAreaThumbProps extends React.ComponentPropsWithoutRef<"div"> {
63
  /**
64
   * Force mount the thumb regardless of visibility conditions
65
   * Useful for controlling animation with React animation libraries
66
   * @default undefined
67
   */
68
  forceMount?: true;
69
}
70

71
type ScrollAreaThumbElement = React.ComponentRef<"div">;
72
```
73

74
**Usage Examples:**
75

76
```typescript
77
import { ScrollAreaThumb } from "@radix-ui/react-scroll-area";
78

79
// Basic thumb
80
<ScrollAreaThumb />
81

82
// Force mounted thumb for animation control
83
<ScrollAreaThumb forceMount />
84

85
// Styled thumb
86
<ScrollAreaThumb 
87
  style={{ 
88
    backgroundColor: '#666',
89
    borderRadius: 4 
90
  }} 
91
/>
92
```
93

94
### Component Aliases
95

96
Shorter alias components for scrollbar system.
97

98
```typescript { .api }
99
const Scrollbar: typeof ScrollAreaScrollbar;
100
const Thumb: typeof ScrollAreaThumb;
101
```
102

103
**Usage Examples:**
104

105
```typescript
106
import { Scrollbar, Thumb } from "@radix-ui/react-scroll-area";
107

108
<Scrollbar orientation="vertical">
109
  <Thumb />
110
</Scrollbar>
111
```
112

113
## Display Modes
114

115
### Auto Mode
116

117
Shows scrollbars only when content overflows the viewport.
118

119
```typescript
120
<ScrollArea type="auto">
121
  <ScrollAreaViewport>
122
    <div>Content</div>
123
  </ScrollAreaViewport>
124
  <ScrollAreaScrollbar orientation="vertical">
125
    <ScrollAreaThumb />
126
  </ScrollAreaScrollbar>
127
</ScrollArea>
128
```
129

130
### Always Mode
131

132
Always shows scrollbars regardless of content overflow.
133

134
```typescript
135
<ScrollArea type="always">
136
  <ScrollAreaViewport>
137
    <div>Content</div>
138
  </ScrollAreaViewport>
139
  <ScrollAreaScrollbar orientation="vertical">
140
    <ScrollAreaThumb />
141
  </ScrollAreaScrollbar>
142
</ScrollArea>
143
```
144

145
### Scroll Mode
146

147
Shows scrollbars during scroll events and user interaction.
148

149
```typescript
150
<ScrollArea type="scroll">
151
  <ScrollAreaViewport>
152
    <div>Content</div>
153
  </ScrollAreaViewport>
154
  <ScrollAreaScrollbar orientation="vertical">
155
    <ScrollAreaThumb />
156
  </ScrollAreaScrollbar>
157
</ScrollArea>
158
```
159

160
### Hover Mode
161

162
Shows scrollbars when hovering over the scroll area (default behavior).
163

164
```typescript
165
<ScrollArea type="hover" scrollHideDelay={1000}>
166
  <ScrollAreaViewport>
167
    <div>Content</div>
168
  </ScrollAreaViewport>
169
  <ScrollAreaScrollbar orientation="vertical">
170
    <ScrollAreaThumb />
171
  </ScrollAreaScrollbar>
172
</ScrollArea>
173
```
174

175
## Scrollbar Behavior
176

177
### Automatic Positioning
178

179
Scrollbars are automatically positioned based on text direction:
180

181
- **LTR layouts**: Vertical scrollbar on the right, horizontal scrollbar on the bottom
182
- **RTL layouts**: Vertical scrollbar on the left, horizontal scrollbar on the bottom
183

184
### Touch Support
185

186
- Scrollbars support pointer events for desktop interaction
187
- Touch scrolling uses native momentum scrolling on mobile devices
188
- Drag interactions work with both mouse and touch input
189

190
### Sizing and Styling
191

192
- Thumb size automatically calculated based on content-to-viewport ratio
193
- Minimum thumb size of 18px (matches macOS standards)
194
- Custom CSS properties available for precise styling control
195
- Scrollbar track padding respected for custom styling
196

197
### Data Attributes
198

199
Components include data attributes for styling:
200

201
- `data-orientation="horizontal|vertical"` on scrollbars
202
- `data-state="visible|hidden"` indicating current visibility
203
- `data-radix-scroll-area-viewport` on viewport elements
204

205
### Event Handling
206

207
- Wheel events are intercepted and managed for custom scrollbar behavior
208
- Pointer capture prevents text selection during scrollbar dragging
209
- Scroll behavior temporarily set to 'auto' during drag operations