Registry / web-framework / normalize-scroll-left

normalize-scroll-left

JSON →
library0.2.1jsnpmunverified

This utility library addresses the inconsistent behavior of the `Element.scrollLeft` property when an element's direction is set to Right-to-Left (RTL) across different browsers. It provides methods to detect the browser's specific `scrollLeft` implementation type (e.g., WebKit's 'default', Firefox/Opera's 'negative', IE/Edge's 'reverse') and then normalize `scrollLeft` values to a consistent, WebKit-like `0` (most left) to `100` (most right) range for both getting and setting. The current stable version is 0.2.1. Releases appear to be driven by bug fixes and feature enhancements, such as ESM support in v0.2.0. Its key differentiator is robust feature detection to abstract away browser quirks, enabling developers to work with a predictable `scrollLeft` API for RTL content, based on established patterns from jQuery plugins and Stack Overflow solutions. It explicitly handles Server-Side Rendering (SSR) environments by returning `indeterminate` or `NaN` for relevant functions, indicating non-browser execution.

npm install normalize-scroll-left
INSTALL
IMPORT
SIG · NORMALIZE-SCROLL-L
N
normalize-scroll-left
web-frameworkjavascriptv0.2.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

detectScrollType
import { detectScrollType } from 'normalize-scroll-left';
const detectScrollType = require('normalize-scroll-left').detectScrollType;
ESM-only since v0.2.0. Function requires a DOM environment and caches its result.
getNormalizedScrollLeft
import { getNormalizedScrollLeft } from 'normalize-scroll-left';
const getNormalizedScrollLeft = require('normalize-scroll-left').getNormalizedScrollLeft;
ESM-only since v0.2.0. Requires explicit 'direction' and returns NaN in non-browser environments.
setNormalizedScrollLeft
import { setNormalizedScrollLeft } from 'normalize-scroll-left';
const setNormalizedScrollLeft = require('normalize-scroll-left').setNormalizedScrollLeft;
ESM-only since v0.2.0. Requires explicit 'direction' and does nothing in non-browser environments.

Demonstrates detecting scroll behavior, creating an RTL scrollable element, and using normalized functions to get and set its scroll position consistently across browsers.

import { detectScrollType, getNormalizedScrollLeft, setNormalizedScrollLeft } from 'normalize-scroll-left'; // This quickstart demonstrates how to use normalize-scroll-left to handle // inconsistent Element.scrollLeft behavior in RTL layouts across browsers. // 1. Detect the browser's scroll type (caches result) // Must be called after the DOM body is loaded. const scrollType = detectScrollType(); console.log(`Detected scroll type: ${scrollType}`); // e.g., 'default', 'negative', 'reverse', 'indeterminate' in SSR // 2. Create a dummy scrollable element for demonstration const container = document.createElement('div'); container.id = 'my-scrollable-container'; container.style.direction = 'rtl'; container.style.width = '100px'; container.style.overflowX = 'scroll'; container.style.whiteSpace = 'nowrap'; container.style.border = '1px solid black'; container.innerHTML = '<span style="display:inline-block; width:200px; height:20px;">Scrollable Content</span>'; document.body.appendChild(container); // Simulate scrolling to the most right (normalized to 100) setNormalizedScrollLeft(container, 100, 'rtl'); console.log(`After setting normalized scrollLeft to 100 (most right): ${getNormalizedScrollLeft(container, 'rtl')}`); // Simulate scrolling to a specific position (normalized to 20) setNormalizedScrollLeft(container, 20, 'rtl'); console.log(`After setting normalized scrollLeft to 20: ${getNormalizedScrollLeft(container, 'rtl')}`); // Clean up document.body.removeChild(container);
Debug
Known issues
breakingVersion 0.2.0 introduced ESM support via the 'module' field. Projects using CommonJS `require()` might need to adjust their import statements or build configurations to properly consume the package, especially if relying on older Node.js versions or specific bundler setups.
fix
Use ESM `import` statements (e.g., `import { name } from 'pkg';`) instead of CommonJS `require()` for newer versions. Ensure your build system is configured to handle ESM modules.
affects: >=0.2.0
gotchaThe `detectScrollType()` function requires a browser DOM environment to operate, as it renders a dummy element. It will return `'indeterminate'` in non-browser (e.g., Node.js/SSR) environments and also if called before `document.body` is fully loaded.
fix
Ensure `detectScrollType()` is called in a client-side context after the DOM is ready (e.g., within a `DOMContentLoaded` listener). For SSR, check for `typeof document !== 'undefined'` before invocation or account for the `'indeterminate'` return type.
affects: >=0.1.0
gotchaBoth `getNormalizedScrollLeft()` and `setNormalizedScrollLeft()` explicitly require the `direction` ('rtl' or 'ltr') as an argument. This is for performance reasons to avoid expensive `getComputedStyle` calls and potential reflows. Providing an incorrect `direction` might lead to unexpected scroll behavior.
fix
Always pass the correct, explicitly known `direction` ('rtl' or 'ltr') corresponding to the element's computed style. Do not rely on the library to infer it.
affects: >=0.1.0
gotchaFunctions like `getNormalizedScrollLeft()` return `NaN` and `setNormalizedScrollLeft()` does nothing when executed in a non-browser environment (e.g., Node.js for SSR). This is by design to avoid DOM access errors.
fix
Implement client-side checks for these functions or handle `NaN` as a possible return value for `getNormalizedScrollLeft()` in universal applications. Avoid calling `setNormalizedScrollLeft()` in SSR contexts where DOM manipulation is not possible.
affects: >=0.1.0
Errors
Common errors & fixes
ReferenceError: document is not defined
Attempting to call `detectScrollType`, `getNormalizedScrollLeft`, or `setNormalizedScrollLeft` in a Node.js (Server-Side Rendering) environment without a browser emulation layer.
fix
Wrap DOM-dependent calls in a client-side check, e.g., `if (typeof document !== 'undefined') { /* call function */ }`, or ensure these functions are only executed on the client-side.
detectScrollType() returns 'indeterminate' in browser
`detectScrollType()` was invoked before the `document.body` was fully loaded or available, preventing it from rendering the necessary dummy element for feature detection.
fix
Ensure that `detectScrollType()` is called only after the DOM is ready, for instance, within a `DOMContentLoaded` event listener or at the end of the `<body>` in traditional scripts.
Scroll position not normalizing correctly for RTL elements.
The `direction` argument passed to `getNormalizedScrollLeft()` or `setNormalizedScrollLeft()` does not match the actual computed `direction` of the `HTMLElement`, or the element's `direction` itself is not correctly set to `rtl`.
fix
Verify that the `direction` argument (e.g., `'rtl'`) explicitly passed to the normalization functions accurately reflects the `getComputedStyle().direction` of the target `HTMLElement`.
Upgrade
Version history
0.2.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
2 hits · last 30 days
node
2
Resources
normalize-scroll-left — npm install normalize-scroll-left · libregistry