SimpleBar React Component

Common errors

• TypeError: Cannot read properties of undefined (reading 'getOptions') or similar polyfill-related errors.

  cause After upgrading to SimpleBar v6.0.0, required browser polyfills (like ResizeObserver or core-js) are no longer bundled by default.
  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.

• Native scrollbar appears instead of the custom SimpleBar scrollbar.

  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.
  fix Ensure 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.

  cause As of SimpleBar v5.0.1, the attached DOM node is no longer mutated. Previous methods of instance retrieval are obsolete.
  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.

• 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>'.

  cause Incorrect typing or missing props definitions for the SimpleBar component in a TypeScript project.
  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.

Warnings

• breaking 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.
  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`).
• breaking 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.
  Fix: Manually include necessary polyfills for your target browsers, for example, by configuring `@babel/preset-env` or using `polyfill.io`.
• breaking 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.
  Fix: Migrate `data-simplebar-options` to direct props on the `SimpleBar` component (e.g., `<SimpleBar forceVisible="y" autoHide={false}>`).
• breaking 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)`.
  Fix: Replace direct property access on DOM nodes with `SimpleBar.instances.get(document.querySelector('[data-simplebar]'))` to retrieve the instance for imperative actions.
• breaking 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.
  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%`).
• gotcha 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.
  Fix: Use SimpleBar for internal, contained scrolling areas within your webpage, such as modals, chat windows, or specific content blocks.
• gotcha 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.
  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.

Install

• npm install simplebar-react npm
• yarn add simplebar-react yarn
• pnpm add simplebar-react pnpm

Imports

• SimpleBar
  wrong:

  const SimpleBar = require('simplebar-react');

  correct:

  import SimpleBar from 'simplebar-react';

  Primary import for the React component. CommonJS `require` is discouraged in modern React projects using ESM.
• CSS
  wrong:

  import 'simplebar/dist/simplebar.min.css';

  correct:

  import 'simplebar-react/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
  wrong:

  import { SimpleBarProps } from 'simplebar-react';

  correct:

  import type { Props as 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.

Quickstart

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;