{"id":12033,"library":"simplebar-react","title":"SimpleBar React Component","description":"SimpleBar-React is a React wrapper component for the core SimpleBar library, which provides highly customizable scrollbars while preserving native browser scroll performance and behaviors. Unlike many other custom scrollbar solutions, it avoids JavaScript-driven scrolling in favor of native `overflow: auto`, ensuring a smooth user experience. The `simplebar-react` package is currently at version 3.3.2. The underlying `simplebar` core library is actively maintained, with version 6.2.7 being stable and a 7.0.0-beta.0 release in progress, indicating a consistent, though not rapid, release cadence for major updates. It is designed for internal scrolling areas (like chat boxes or specific content panels) and explicitly warns against use on the `document.body`. It ships with TypeScript definitions and supports modern React versions.","status":"active","version":"3.3.2","language":"javascript","source_language":"en","source_url":"https://github.com/grsmto/simplebar","tags":["javascript","typescript"],"install":[{"cmd":"npm install simplebar-react","lang":"bash","label":"npm"},{"cmd":"yarn add simplebar-react","lang":"bash","label":"yarn"},{"cmd":"pnpm add simplebar-react","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for the React component.","package":"react","optional":false}],"imports":[{"note":"Primary import for the React component. CommonJS `require` is discouraged in modern React projects using ESM.","wrong":"const SimpleBar = require('simplebar-react');","symbol":"SimpleBar","correct":"import SimpleBar from 'simplebar-react';"},{"note":"The CSS file must be imported from the `simplebar-react` package, not the core `simplebar` package, as there was a past documentation typo.","wrong":"import 'simplebar/dist/simplebar.min.css';","symbol":"CSS","correct":"import 'simplebar-react/dist/simplebar.min.css';"},{"note":"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.","wrong":"import { SimpleBarProps } from 'simplebar-react';","symbol":"SimpleBarProps","correct":"import type { Props as SimpleBarProps } from 'simplebar-react';"}],"quickstart":{"code":"import React from 'react';\nimport SimpleBar from 'simplebar-react';\nimport 'simplebar-react/dist/simplebar.min.css';\n\nconst MyScrollableContent = () => (\n  <SimpleBar style={{ maxHeight: 300, border: '1px solid #ccc', padding: '10px' }}>\n    <div style={{ paddingRight: '20px' }}>\n      <p>This is some content that will eventually overflow the container.</p>\n      <p>SimpleBar will provide a custom styled scrollbar for this area.</p>\n      <p>It maintains native scrolling behavior for optimal performance.</p>\n      <p>You can customize the appearance of the scrollbar using CSS variables.</p>\n      <p>Remember not to use SimpleBar on the entire document body.</p>\n      <p>More content to make it scrollable...</p>\n      <p>Line 7</p>\n      <p>Line 8</p>\n      <p>Line 9</p>\n      <p>Line 10</p>\n      <p>Line 11</p>\n      <p>Line 12</p>\n      <p>Line 13</p>\n      <p>Line 14</p>\n      <p>Line 15</p>\n      <p>Line 16</p>\n      <p>Line 17</p>\n      <p>Line 18</p>\n      <p>Line 19</p>\n      <p>Line 20</p>\n    </div>\n  </SimpleBar>\n);\n\nexport default MyScrollableContent;","lang":"typescript","description":"This quickstart demonstrates how to integrate `SimpleBar` into a React component, showing a basic scrollable area with custom scrollbars and imported CSS."},"warnings":[{"fix":"Ensure 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`).","message":"SimpleBar 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.","severity":"breaking","affected_versions":">=simplebar@7.0.0-beta.0"},{"fix":"Manually include necessary polyfills for your target browsers, for example, by configuring `@babel/preset-env` or using `polyfill.io`.","message":"SimpleBar 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.","severity":"breaking","affected_versions":">=simplebar@6.0.0"},{"fix":"Migrate `data-simplebar-options` to direct props on the `SimpleBar` component (e.g., `<SimpleBar forceVisible=\"y\" autoHide={false}>`).","message":"In `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.","severity":"breaking","affected_versions":">=simplebar-react@5.0.1"},{"fix":"Replace direct property access on DOM nodes with `SimpleBar.instances.get(document.querySelector('[data-simplebar]'))` to retrieve the instance for imperative actions.","message":"SimpleBar v5.0.1 (core library) no longer mutates the attached DOM node. To retrieve a SimpleBar instance, you must use `SimpleBar.instances.get(element)`.","severity":"breaking","affected_versions":">=simplebar@5.0.1"},{"fix":"Adjust 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%`).","message":"SimpleBar 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.","severity":"breaking","affected_versions":">=simplebar@4.0.0"},{"fix":"Use SimpleBar for internal, contained scrolling areas within your webpage, such as modals, chat windows, or specific content blocks.","message":"SimpleBar 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.","severity":"gotcha","affected_versions":">=simplebar@4.0.0"},{"fix":"Avoid 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.","message":"Styling 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.","severity":"gotcha","affected_versions":">=simplebar@4.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Add 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.","cause":"After upgrading to SimpleBar v6.0.0, required browser polyfills (like ResizeObserver or core-js) are no longer bundled by default.","error":"TypeError: Cannot read properties of undefined (reading 'getOptions') or similar polyfill-related errors."},{"fix":"Ensure the element you apply SimpleBar to has a defined height, e.g., `style={{ height: '100%' }}` or `maxHeight` via CSS or props.","cause":"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.","error":"Native scrollbar appears instead of the custom SimpleBar scrollbar."},{"fix":"Retrieve 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.","cause":"As of SimpleBar v5.0.1, the attached DOM node is no longer mutated. Previous methods of instance retrieval are obsolete.","error":"SimpleBar instance cannot be retrieved using direct DOM node properties or old methods."},{"fix":"Ensure 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.","cause":"Incorrect typing or missing props definitions for the SimpleBar component in a TypeScript project.","error":"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>'."}],"ecosystem":"npm"}