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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SimpleBar
✓ import SimpleBar from 'simplebar-react';
✗ const SimpleBar = require('simplebar-react');
Primary import for the React component. CommonJS `require` is discouraged in modern React projects using ESM.
CSS
✓ import 'simplebar-react/dist/simplebar.min.css';
✗ import 'simplebar/dist/simplebar.min.css';
The CSS file must be imported from the `simplebar-react` package, not the core `simplebar` package, as there was a past documentation typo.
SimpleBarProps
✓ import type { Props as SimpleBarProps } from 'simplebar-react';
✗ import { SimpleBarProps } from 'simplebar-react';
For TypeScript users, import the component's props type using `import type` from 'simplebar-react'. The main props type is exported as `Props` and can be aliased.
This quickstart demonstrates how to integrate `SimpleBar` into a React component, showing a basic scrollable area with custom scrollbars and imported CSS.
import React from 'react';
import SimpleBar from 'simplebar-react';
import 'simplebar-react/dist/simplebar.min.css';
const MyScrollableContent = () => (
<SimpleBar style={{ maxHeight: 300, border: '1px solid #ccc', padding: '10px' }}>
<div style={{ paddingRight: '20px' }}>
<p>This is some content that will eventually overflow the container.</p>
<p>SimpleBar will provide a custom styled scrollbar for this area.</p>
<p>It maintains native scrolling behavior for optimal performance.</p>
<p>You can customize the appearance of the scrollbar using CSS variables.</p>
<p>Remember not to use SimpleBar on the entire document body.</p>
<p>More content to make it scrollable...</p>
<p>Line 7</p>
<p>Line 8</p>
<p>Line 9</p>
<p>Line 10</p>
<p>Line 11</p>
<p>Line 12</p>
<p>Line 13</p>
<p>Line 14</p>
<p>Line 15</p>
<p>Line 16</p>
<p>Line 17</p>
<p>Line 18</p>
<p>Line 19</p>
<p>Line 20</p>
</div>
</SimpleBar>
);
export default MyScrollableContent;
Debug
Known issues
breakingSimpleBar v7.0.0-beta.0 (core library) drops support for browsers that do not natively support scrollbar hiding via CSS. This removed several internal DOM elements, potentially affecting custom CSS targeting these elements.fixEnsure target browsers support CSS scrollbar hiding. Update custom CSS to reflect changes in SimpleBar's internal DOM structure (e.g., removal of `.simplebar-height-auto-observer`).
affects: >=simplebar@7.0.0-beta.0
breakingSimpleBar v6.0.0 (core library) was largely rewritten in TypeScript and no longer includes polyfills (like `ResizeObserver` or `core-js`) by default. This can lead to errors in older or less-supported browsers.fixManually include necessary polyfills for your target browsers, for example, by configuring `@babel/preset-env` or using `polyfill.io`.
affects: >=simplebar@6.0.0
breakingIn `simplebar-react` v5.0.1, the method of passing options changed from `data-attributes` to direct React props. The `data-attribute` approach is now deprecated.fixMigrate `data-simplebar-options` to direct props on the `SimpleBar` component (e.g., `<SimpleBar forceVisible="y" autoHide={false}>`). affects: >=simplebar-react@5.0.1
breakingSimpleBar v5.0.1 (core library) no longer mutates the attached DOM node. To retrieve a SimpleBar instance, you must use `SimpleBar.instances.get(element)`.fixReplace direct property access on DOM nodes with `SimpleBar.instances.get(document.querySelector('[data-simplebar]'))` to retrieve the instance for imperative actions. affects: >=simplebar@5.0.1
breakingSimpleBar v4.0.0 (core library) introduced a new internal wrapper `.simplebar-content-wrapper` and changed the behavior of `getScrollElement()`. It also stopped applying `height: inherit` to the container.fixAdjust any CSS or JavaScript code that depends on the internal DOM structure. Use `getContentElement()` instead of `getScrollElement()` to access the content element. Ensure your SimpleBar container element has an explicit height (e.g., `height: 100%`).
affects: >=simplebar@4.0.0
gotchaSimpleBar is not designed for wrapping the entire `body` element. Doing so can negatively impact user experience, leading to slower scroll performance and loss of native scroll behaviors.fixUse SimpleBar for internal, contained scrolling areas within your webpage, such as modals, chat windows, or specific content blocks.
affects: >=simplebar@4.0.0
gotchaStyling clashes are a common issue. If the element SimpleBar is applied to has conflicting CSS properties, it can lead to unexpected behavior or visible native scrollbars.fixAvoid styling the SimpleBar host element directly. Instead, apply styles to an inner element or use the CSS variables provided by SimpleBar for customization. Refer to `simplebar.css` for structural guidance.
affects: >=simplebar@4.0.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'getOptions') or similar polyfill-related errors.
After upgrading to SimpleBar v6.0.0, required browser polyfills (like ResizeObserver or core-js) are no longer bundled by default.
fixAdd polyfills to your project explicitly. For example, use Babel with `@babel/preset-env` or import `resize-observer-polyfill` if targeting browsers like iOS Safari or Edge.
Native scrollbar appears instead of the custom SimpleBar scrollbar.
From SimpleBar v4.0.0 onwards, the library no longer applies `height: inherit` to the container. If your container element lacks an explicit height, the native scrollbar will appear.
fixEnsure the element you apply SimpleBar to has a defined height, e.g., `style={{ height: '100%' }}` or `maxHeight` via CSS or props. SimpleBar instance cannot be retrieved using direct DOM node properties or old methods.
As of SimpleBar v5.0.1, the attached DOM node is no longer mutated. Previous methods of instance retrieval are obsolete.
fixRetrieve the SimpleBar instance using `SimpleBar.instances.get(document.querySelector('[data-simplebar]'))` for non-React scenarios, or leverage `scrollableNodeProps` with `useRef` in React to get a ref to the underlying scrollable element. TypeScript error: Type '{ children: Element; forceVisible: string; autoHide: boolean; }' is not assignable to type 'IntrinsicAttributes & RefAttributes<any>'. Property 'children' does not exist on type 'IntrinsicAttributes & RefAttributes<any>'.
Incorrect typing or missing props definitions for the SimpleBar component in a TypeScript project.
fixEnsure you are passing valid `SimpleBarProps` to the component and that your TypeScript setup correctly recognizes them. If using `children`, ensure they are correctly typed as `React.ReactNode`. Review `SimpleBar` documentation for available props.
Audit
Dependencies
reactrequiredPeer dependency for the React component.