<commit_before># SimpleBar [![npm package][npm-badge]][npm] ![size-badge]

:warning: SimpleBar v5 is here! There are some **breaking changes!** Make sure to check out [the changelog](https://github.com/Grsmto/simplebar/releases) before updating.

SimpleBar is a plugin that tries to solve a long time problem: how to get custom scrollbars for your web-app while keeping a good user experience?
SimpleBar **does NOT implement a custom scroll behaviour**. It keeps the **native** `overflow: auto` scroll and **only** replace the scrollbar visual appearance.

SimpleBar is meant to be as easy to use as possible and lightweight. If you want something more advanced I recommend [KingSora](https://github.com/KingSora) 's [Overlay Scrollbars](https://kingsora.github.io/OverlayScrollbars/).

### Installation

**- Via npm**
`npm install simplebar --save`

**- Via Yarn**
`yarn add simplebar`

**- Via `<script>` tag**

```html
<link
  rel="stylesheet"
  href="https://unpkg.com/simplebar@latest/dist/simplebar.css"
/>
<script src="https://unpkg.com/simplebar@latest/dist/simplebar.min.js"></script>
<!-- or -->
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/simplebar@latest/dist/simplebar.css"
/>
<script src="https://cdn.jsdelivr.net/npm/simplebar@latest/dist/simplebar.min.js"></script>
```

note: you should replace `@latest` to the latest version (ex `@2.4.3`), if you want to lock to a specific version.
You can find the full list of modules available [there](https://unpkg.com/simplebar@latest/dist/).

### Usage

Check out the [React](https://github.com/Grsmto/simplebar/blob/master/examples/react/src/App.js) and [Vue](https://github.com/Grsmto/simplebar/blob/master/examples/vue/src/App.vue) examples.

If you are using Gatsby, please see [#345](https://github.com/Grsmto/simplebar/issues/345).

If you are using a module loader (like Webpack) you first need to load SimpleBar:

```js
import 'simplebar'; // or "import SimpleBar from 'simplebar';" if you want to use it manually.
import 'simplebar/dist/simplebar.css';
```

Set `data-simplebar` on the element you want your custom scrollbar. You're done.

```html
<div data-simplebar></div>
```

**Don't forget to import both css and js in your project!**

### Noscript support

To make sure your elements are scrollable when JavaScript is disabled, it's important to include this snippet in your `<head>` to reset scrolling:

```js
<noscript>
  <style>
    /**
    * Reinstate scrolling for non-JS clients
    */
    .simplebar-content-wrapper {
      overflow: auto;
    }
  </style>
</noscript>
```

### :warning: Warning!

SimpleBar is **not intended to be used on the `body` element!** I don't recommend wrapping your entire web page inside a custom scroll as it will often badly affect the user experience (slower scroll performance compared to the native body scroll, no native scroll behaviours like click on track, etc.). Do it at your own risk! SimpleBar is meant to improve the experience of **internal web page scrolling**; such as a chat box or a small scrolling area. **Please read the [caveats](#5-caveats) section first to be aware of the limitations!**

### Troubleshooting

If you are experiencing issues when setting up SimpleBar, it is most likely because your styles are clashing with SimpleBar ones. Make sure the element you are setting SimpleBar on does not override any SimpleBar css properties! **We recommend to not style that element at all and use an inner element instead.**

### Sponsors

Thanks to BrowserStack for sponsoring open source projects and letting us test SimpleBar for free.
<a href="https://www.browserstack.com" target="_blank">
<img src="https://user-images.githubusercontent.com/15015324/45184727-368fbf80-b1fe-11e8-8827-08dbc80b0fb1.png" width="200">
</a>

---

1. [Documentation](#1-documentation)
2. [Browsers support](#2-browsers-support)
3. [Demo](#3-demo)
4. [How it works](#4-how-it-works)
5. [Caveats](#5-caveats)
6. [Changelog](#6-changelog)
7. [Credits](#7-credits)

## 1. Documentation

### Other usages

You can start SimpleBar manually if you need to:

```js
new SimpleBar(document.getElementById('myElement'));
```

or

```js
Array.prototype.forEach.call(
  document.querySelectorAll('.myElements'),
  el => new SimpleBar()
);
```

If you want to use jQuery:

```js
new SimpleBar($('#myElement')[0]);
```

or

```js
$('.myElements').each(element, new SimpleBar());
```

### Styling

The default styling is applied with CSS. There is no "built-in" way to style the scrollbar, you just need to override the default CSS.

Ex, to change the color of the scrollbar:
```css
.simplebar-scrollbar::before {
  background-color: red;
}
```

### Options

Options can be applied to the plugin during initialization:

```js
new SimpleBar(document.getElementById('myElement'), {
  option1: value1,
  option2: value2
});
```

or using data-attributes:

```html
<div data-simplebar data-simplebar-auto-hide="false"></div>
```

Available options are:

#### autoHide

By default SimpleBar automatically hides the scrollbar if the user is not scrolling (it emulates Mac OSX Lion's scrollbar). You can make the scrollbar always visible by setting the `autoHide` option to `false`:

```js
new SimpleBar(document.getElementById('myElement'), { autoHide: false });
```

Default value is `true`.

You can also control the animation via CSS as it's a simple CSS opacity transition.

#### scrollbarMinSize

Define the minimum scrollbar size in pixels.

Default value is `10`.

#### classNames

It is possible to change the default class names that SimpleBar uses. To get your own styles to work refer to `simplebar.css` to get an idea how to setup your css.

- `content` represents the wrapper for the content being scrolled.
- `scrollContent` represents the container containing the elements being scrolled.
- `scrollbar` defines the style of the scrollbar with which the user can interact to scroll the content.
- `track` styles the area surrounding the `scrollbar`.

```js
classNames: {
  // defaults
  content: 'simplebar-content',
  scrollContent: 'simplebar-scroll-content',
  scrollbar: 'simplebar-scrollbar',
  track: 'simplebar-track'
}
```

#### forceVisible

You can force the track to be visible (same behaviour as `overflow: scroll`) using the `forceVisible` option:

```
forceVisible: true|'x'|'y' (default to `false`)
```<commit_msg>doc: remove duplicate "scrollbarMinSize" option (fix #442)<commit_after># SimpleBar [![npm package][npm-badge]][npm] ![size-badge]

:warning: SimpleBar v5 is here! There are some **breaking changes!** Make sure to check out [the changelog](https://github.com/Grsmto/simplebar/releases) before updating.

SimpleBar is a plugin that tries to solve a long time problem: how to get custom scrollbars for your web-app while keeping a good user experience?
SimpleBar **does NOT implement a custom scroll behaviour**. It keeps the **native** `overflow: auto` scroll and **only** replace the scrollbar visual appearance.

SimpleBar is meant to be as easy to use as possible and lightweight. If you want something more advanced I recommend [KingSora](https://github.com/KingSora) 's [Overlay Scrollbars](https://kingsora.github.io/OverlayScrollbars/).

### Installation

**- Via npm**
`npm install simplebar --save`

**- Via Yarn**
`yarn add simplebar`

**- Via `<script>` tag**

```html
<link
  rel="stylesheet"
  href="https://unpkg.com/simplebar@latest/dist/simplebar.css"
/>
<script src="https://unpkg.com/simplebar@latest/dist/simplebar.min.js"></script>
<!-- or -->
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/simplebar@latest/dist/simplebar.css"
/>
<script src="https://cdn.jsdelivr.net/npm/simplebar@latest/dist/simplebar.min.js"></script>
```

note: you should replace `@latest` to the latest version (ex `@2.4.3`), if you want to lock to a specific version.
You can find the full list of modules available [there](https://unpkg.com/simplebar@latest/dist/).

### Usage

Check out the [React](https://github.com/Grsmto/simplebar/blob/master/examples/react/src/App.js) and [Vue](https://github.com/Grsmto/simplebar/blob/master/examples/vue/src/App.vue) examples.

If you are using Gatsby, please see [#345](https://github.com/Grsmto/simplebar/issues/345).

If you are using a module loader (like Webpack) you first need to load SimpleBar:

```js
import 'simplebar'; // or "import SimpleBar from 'simplebar';" if you want to use it manually.
import 'simplebar/dist/simplebar.css';
```

Set `data-simplebar` on the element you want your custom scrollbar. You're done.

```html
<div data-simplebar></div>
```

**Don't forget to import both css and js in your project!**

### Noscript support

To make sure your elements are scrollable when JavaScript is disabled, it's important to include this snippet in your `<head>` to reset scrolling:

```js
<noscript>
  <style>
    /**
    * Reinstate scrolling for non-JS clients
    */
    .simplebar-content-wrapper {
      overflow: auto;
    }
  </style>
</noscript>
```

### :warning: Warning!

SimpleBar is **not intended to be used on the `body` element!** I don't recommend wrapping your entire web page inside a custom scroll as it will often badly affect the user experience (slower scroll performance compared to the native body scroll, no native scroll behaviours like click on track, etc.). Do it at your own risk! SimpleBar is meant to improve the experience of **internal web page scrolling**; such as a chat box or a small scrolling area. **Please read the [caveats](#5-caveats) section first to be aware of the limitations!**

### Troubleshooting

If you are experiencing issues when setting up SimpleBar, it is most likely because your styles are clashing with SimpleBar ones. Make sure the element you are setting SimpleBar on does not override any SimpleBar css properties! **We recommend to not style that element at all and use an inner element instead.**

### Sponsors

Thanks to BrowserStack for sponsoring open source projects and letting us test SimpleBar for free.
<a href="https://www.browserstack.com" target="_blank">
<img src="https://user-images.githubusercontent.com/15015324/45184727-368fbf80-b1fe-11e8-8827-08dbc80b0fb1.png" width="200">
</a>

---

1. [Documentation](#1-documentation)
2. [Browsers support](#2-browsers-support)
3. [Demo](#3-demo)
4. [How it works](#4-how-it-works)
5. [Caveats](#5-caveats)
6. [Changelog](#6-changelog)
7. [Credits](#7-credits)

## 1. Documentation

### Other usages

You can start SimpleBar manually if you need to:

```js
new SimpleBar(document.getElementById('myElement'));
```

or

```js
Array.prototype.forEach.call(
  document.querySelectorAll('.myElements'),
  el => new SimpleBar()
);
```

If you want to use jQuery:

```js
new SimpleBar($('#myElement')[0]);
```

or

```js
$('.myElements').each(element, new SimpleBar());
```

### Styling

The default styling is applied with CSS. There is no "built-in" way to style the scrollbar, you just need to override the default CSS.

Ex, to change the color of the scrollbar:
```css
.simplebar-scrollbar::before {
  background-color: red;
}
```

### Options

Options can be applied to the plugin during initialization:

```js
new SimpleBar(document.getElementById('myElement'), {
  option1: value1,
  option2: value2
});
```

or using data-attributes:

```html
<div data-simplebar data-simplebar-auto-hide="false"></div>
```

Available options are:

#### autoHide

By default SimpleBar automatically hides the scrollbar if the user is not scrolling (it emulates Mac OSX Lion's scrollbar). You can make the scrollbar always visible by setting the `autoHide` option to `false`:

```js
new SimpleBar(document.getElementById('myElement'), { autoHide: false });
```

Default value is `true`.

You can also control the animation via CSS as it's a simple CSS opacity transition.

#### classNames

It is possible to change the default class names that SimpleBar uses. To get your own styles to work refer to `simplebar.css` to get an idea how to setup your css.

- `content` represents the wrapper for the content being scrolled.
- `scrollContent` represents the container containing the elements being scrolled.
- `scrollbar` defines the style of the scrollbar with which the user can interact to scroll the content.
- `track` styles the area surrounding the `scrollbar`.

```js
classNames: {
  // defaults
  content: 'simplebar-content',
  scrollContent: 'simplebar-scroll-content',
  scrollbar: 'simplebar-scrollbar',
  track: 'simplebar-track'
}
```

#### forceVisible

You can force the track to be visible (same behaviour as `overflow: scroll`) using the `forceVisible` option:

```
forceVisible: true|'x'|'y' (default to `false`)
```
{'fraction_non_alphanumeric': 0.12559241706161137, 'fraction_numerical': 0.011295418641390205, 'mean_word_length': 4.624611283873834, 'pattern_counts': {'":': 0, '<': 43, '<?xml version=': 0, '>': 45, 'https://': 26, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6585330', 'n_tokens_mistral': 3944, 'n_tokens_neox': 3738, 'n_words': 1454}