0
# Smoothscroll Polyfill
1

2
Smoothscroll Polyfill provides a polyfill implementation of the Scroll Behavior specification, enabling smooth scrolling functionality in browsers that don't natively support the CSS scroll-behavior property. The polyfill detects native support and only activates when necessary, providing smooth scrolling behavior for scrollTo(), scrollIntoView(), and similar methods.
3

4
## Package Information
5

6
- **Package Name**: smoothscroll-polyfill
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES5)
9
- **Installation**: `npm install smoothscroll-polyfill`
10

11
## Core Imports
12

13
ESM (ES Modules):
14
```javascript
15
import smoothscroll from 'smoothscroll-polyfill';
16
```
17

18
CommonJS:
19
```javascript
20
const smoothscroll = require('smoothscroll-polyfill');
21
```
22

23
Script tag (auto-executes):
24
```html
25
<script src="https://unpkg.com/smoothscroll-polyfill/dist/smoothscroll.min.js"></script>
26
```
27

28
## Basic Usage
29

30
```javascript
31
import smoothscroll from 'smoothscroll-polyfill';
32

33
// Activate the polyfill
34
smoothscroll.polyfill();
35

36
// Now you can use smooth scrolling behavior
37
window.scrollTo({ top: 500, behavior: 'smooth' });
38

39
// Or on elements
40
document.getElementById('myDiv').scrollIntoView({ behavior: 'smooth' });
41
```
42

43
## Architecture
44

45
The polyfill follows a conservative activation strategy:
46
- **Native Detection**: Checks for native CSS scroll-behavior support
47
- **Conditional Override**: Only overrides native methods when necessary
48
- **Method Preservation**: Stores original scroll methods for fallback
49
- **Animation Engine**: Uses requestAnimationFrame for smooth animations
50
- **Browser Compatibility**: Handles IE/Edge rounding differences
51

52
## Capabilities
53

54
### Polyfill Activation
55

56
Activates the smooth scroll polyfill by overriding native browser scroll methods.
57

58
```javascript { .api }
59
/**
60
 * Activates the smooth scroll polyfill
61
 * Checks for 'scrollBehavior' in document.documentElement.style and only overrides 
62
 * native methods if it's not supported or if window.__forceSmoothScrollPolyfill__ is true
63
 * When activated, overrides window.scroll, window.scrollBy, and Element prototype scroll methods
64
 */
65
function polyfill(): void;
66
```
67

68
### Enhanced Window Scroll Methods
69

70
Once the polyfill is activated, these native browser methods are enhanced with smooth scrolling support:
71

72
#### Window.scrollTo / Window.scroll
73

74
Enhanced to support smooth scrolling behavior.
75

76
```javascript { .api }
77
/**
78
 * Scrolls the window to specified coordinates with optional smooth behavior
79
 * @param {Object} options - Scroll options object with coordinates and behavior
80
 * @param {number} [options.left] - Horizontal scroll position in pixels
81
 * @param {number} [options.top] - Vertical scroll position in pixels  
82
 * @param {string} [options.behavior] - Scroll behavior: 'smooth', 'auto', or 'instant'
83
 */
84
window.scrollTo(options);
85
window.scroll(options);
86

87
/**
88
 * Legacy signature: scrolls to specific coordinates
89
 * @param {number} x - Horizontal scroll position in pixels
90
 * @param {number} y - Vertical scroll position in pixels
91
 */
92
window.scrollTo(x, y);
93
window.scroll(x, y);
94
```
95

96
#### Window.scrollBy
97

98
Enhanced to support relative smooth scrolling.
99

100
```javascript { .api }
101
/**
102
 * Scrolls the window by specified amounts with optional smooth behavior
103
 * @param {Object} options - Scroll options object with relative coordinates and behavior
104
 * @param {number} [options.left] - Horizontal scroll offset in pixels
105
 * @param {number} [options.top] - Vertical scroll offset in pixels
106
 * @param {string} [options.behavior] - Scroll behavior: 'smooth', 'auto', or 'instant'
107
 */
108
window.scrollBy(options);
109

110
/**
111
 * Legacy signature: scrolls by specific amounts
112
 * @param {number} x - Horizontal scroll offset in pixels
113
 * @param {number} y - Vertical scroll offset in pixels
114
 */
115
window.scrollBy(x, y);
116
```
117

118
### Enhanced Element Scroll Methods
119

120
Element scroll methods are also enhanced with smooth scrolling support:
121

122
#### Element.scrollTo / Element.scroll
123

124
Enhanced element scrolling with smooth behavior support.
125

126
```javascript { .api }
127
/**
128
 * Scrolls element to specified coordinates with optional smooth behavior
129
 * @param {Object} options - Scroll options object with coordinates and behavior
130
 * @param {number} [options.left] - Horizontal scroll position in pixels
131
 * @param {number} [options.top] - Vertical scroll position in pixels
132
 * @param {string} [options.behavior] - Scroll behavior: 'smooth', 'auto', or 'instant'
133
 */
134
Element.prototype.scrollTo(options);
135
Element.prototype.scroll(options);
136

137
/**
138
 * Legacy signature: scrolls element to specific coordinates
139
 * @param {number} x - Horizontal scroll position in pixels
140
 * @param {number} y - Vertical scroll position in pixels
141
 */
142
Element.prototype.scrollTo(x, y);
143
Element.prototype.scroll(x, y);
144
```
145

146
#### Element.scrollBy
147

148
Enhanced element relative scrolling with smooth behavior support.
149

150
```javascript { .api }
151
/**
152
 * Scrolls element by specified amounts with optional smooth behavior
153
 * @param {Object} options - Scroll options object with relative coordinates and behavior
154
 * @param {number} [options.left] - Horizontal scroll offset in pixels
155
 * @param {number} [options.top] - Vertical scroll offset in pixels
156
 * @param {string} [options.behavior] - Scroll behavior: 'smooth', 'auto', or 'instant'
157
 */
158
Element.prototype.scrollBy(options);
159

160
/**
161
 * Legacy signature: scrolls element by specific amounts
162
 * @param {number} x - Horizontal scroll offset in pixels
163
 * @param {number} y - Vertical scroll offset in pixels
164
 */
165
Element.prototype.scrollBy(x, y);
166
```
167

168
#### Element.scrollIntoView
169

170
Enhanced to support smooth scroll behavior when bringing elements into view.
171

172
```javascript { .api }
173
/**
174
 * Scrolls element into view with optional smooth behavior
175
 * @param {Object|boolean} [options] - Scroll into view options or boolean alignToTop
176
 * @param {string} [options.behavior] - Scroll behavior: 'smooth', 'auto', or 'instant'
177
 */
178
Element.prototype.scrollIntoView(options?: {behavior?: string}): void;
179

180
/**
181
 * Legacy signature: scrolls element into view
182
 * @param {boolean} [alignToTop] - If true, aligns to top; if false, aligns to bottom
183
 */
184
Element.prototype.scrollIntoView(alignToTop?: boolean): void;
185
```
186

187
## Configuration
188

189
### Force Polyfill Override
190

191
Global variable to force the polyfill to override native implementations even when supported.
192

193
```javascript { .api }
194
/**
195
 * Global flag to force polyfill activation even when native support exists
196
 * Must be set before loading/calling the polyfill
197
 * @default undefined
198
 */
199
declare global {
200
  interface Window {
201
    __forceSmoothScrollPolyfill__?: boolean;
202
  }
203
}
204
```
205

206
Usage:
207
```javascript
208
// Set before importing/loading the polyfill
209
window.__forceSmoothScrollPolyfill__ = true;
210

211
// Then load and activate
212
import smoothscroll from 'smoothscroll-polyfill';
213
smoothscroll.polyfill();
214
```
215

216
## Types
217

218
```javascript { .api }
219
interface ScrollToOptions {
220
  left?: number;
221
  top?: number;
222
  behavior?: 'auto' | 'smooth' | 'instant';
223
}
224

225
interface ScrollIntoViewOptions {
226
  behavior?: 'auto' | 'smooth' | 'instant';
227
}
228
```
229

230
## Error Handling
231

232
The polyfill handles several error conditions:
233

234
- **Invalid behavior values**: Throws `TypeError` with message "behavior member of ScrollOptions [value] is not a valid value for enumeration ScrollBehavior." for unsupported behavior values (line 101-105)
235
- **Invalid element scroll parameters**: Throws `SyntaxError` with message "Value could not be converted" when a single number is passed to element scroll methods without a second parameter (matching Firefox behavior, line 318-320)
236
- **Browser compatibility**: Gracefully handles IE/Edge rounding differences with ROUNDING_TOLERANCE constant (line 52)
237

238
## Browser Support
239

240
- **Native support**: Chrome, Firefox, Opera (polyfill automatically detects native 'scrollBehavior' support and skips)
241
- **Polyfill support**: Safari 6+, Internet Explorer 9+, Microsoft Edge 12+, Opera Next
242
- **Microsoft browsers**: Special handling for IE/Edge rounding differences with ROUNDING_TOLERANCE (detects 'MSIE ', 'Trident/', 'Edge/' in user agent)
243
- **Critical dependencies**: Requires `requestAnimationFrame` and `performance.now` (needs polyfills for older browsers)
244
- **DOM dependencies**: Requires `window.getComputedStyle` and `getBoundingClientRect`
245

246
## Usage Examples
247

248
### Basic smooth scrolling
249
```javascript
250
import smoothscroll from 'smoothscroll-polyfill';
251
smoothscroll.polyfill();
252

253
// Smooth scroll to top
254
window.scrollTo({ top: 0, behavior: 'smooth' });
255

256
// Smooth scroll by amount
257
window.scrollBy({ top: 200, behavior: 'smooth' });
258
```
259

260
### Element scrolling
261
```javascript
262
const container = document.getElementById('scrollable-container');
263

264
// Smooth scroll element content
265
container.scrollTo({ top: 100, left: 50, behavior: 'smooth' });
266

267
// Smooth scroll element into view
268
document.getElementById('target').scrollIntoView({ behavior: 'smooth' });
269
```
270

271
### Force override native implementation
272
```javascript
273
// Set global flag before loading
274
window.__forceSmoothScrollPolyfill__ = true;
275

276
import smoothscroll from 'smoothscroll-polyfill';
277
smoothscroll.polyfill();
278

279
// Now all scroll methods use the polyfill implementation
280
window.scrollTo({ top: 500, behavior: 'smooth' });
281
```