| 1 | # SimpleBar [![npm package][npm-badge]][npm] ![size-badge]
|
| 2 |
|
| 3 | 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?
|
| 4 | SimpleBar **does NOT implement a custom scroll behaviour**. It keeps the **native** `overflow: auto` scroll and **only** replace the scrollbar visual appearance.
|
| 5 |
|
| 6 | 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/).
|
| 7 |
|
| 8 | - **🐦 Follow me on [Twitter!](https://twitter.com/adriendenat) or [Mastodon!](https://mas.to/@adrien)**
|
| 9 | - **👨💻 I'm available for hire! [Reach out to me!](https://adriendenat.com/)**
|
| 10 | - **🚧 Check out my new project [Scroll Snap Carousel](https://github.com/Grsmto/scroll-snap-carousel)!**
|
| 11 |
|
| 12 | ### Installation
|
| 13 |
|
| 14 | **- Via npm**
|
| 15 | `npm install simplebar resize-observer-polyfill --save`
|
| 16 |
|
| 17 | **- Via Yarn**
|
| 18 | `yarn add simplebar resize-observer-polyfill`
|
| 19 |
|
| 20 | **- Via `<script>` tag**
|
| 21 |
|
| 22 | ```html
|
| 23 | <link
|
| 24 | rel="stylesheet"
|
| 25 | href="https://unpkg.com/simplebar@latest/dist/simplebar.css"
|
| 26 | />
|
| 27 | <script src="https://unpkg.com/simplebar@latest/dist/simplebar.min.js"></script>
|
| 28 | <!-- or -->
|
| 29 | <link
|
| 30 | rel="stylesheet"
|
| 31 | href="https://cdn.jsdelivr.net/npm/simplebar@latest/dist/simplebar.css"
|
| 32 | />
|
| 33 | <script src="https://cdn.jsdelivr.net/npm/simplebar@latest/dist/simplebar.min.js"></script>
|
| 34 | ```
|
| 35 |
|
| 36 | note: you should replace `@latest` to the latest version (ex `@2.4.3`), if you want to lock to a specific version.
|
| 37 | You can find the full list of modules available [there](https://unpkg.com/simplebar@latest/dist/).
|
| 38 |
|
| 39 | ### Usage
|
| 40 |
|
| 41 | 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.
|
| 42 |
|
| 43 | If you are using a module loader (like Webpack) you first need to load SimpleBar:
|
| 44 |
|
| 45 | ```js
|
| 46 | import 'simplebar'; // or "import SimpleBar from 'simplebar';" if you want to use it manually.
|
| 47 | import 'simplebar/dist/simplebar.css';
|
| 48 |
|
| 49 | // You will need a ResizeObserver polyfill for browsers that don't support it! (iOS Safari, Edge, ...)
|
| 50 | import ResizeObserver from 'resize-observer-polyfill';
|
| 51 | window.ResizeObserver = ResizeObserver;
|
| 52 | ```
|
| 53 |
|
| 54 | You might also need other polyfills as SimpleBar comes with basic browser support only.
|
| 55 | You can use Babel `@babel/preset-env` to polyfill for you, see our [examples package](https://github.com/Grsmto/simplebar/blob/next/packages/examples/.babelrc#L2) or check out [polyfill.io](https://polyfill.io/).
|
| 56 |
|
| 57 | Set `data-simplebar` on the element you want your custom scrollbar. You're done.
|
| 58 |
|
| 59 | ```html
|
| 60 | <div data-simplebar></div>
|
| 61 | ```
|
| 62 |
|
| 63 | **Don't forget to import both css and js in your project!**
|
| 64 |
|
| 65 | ### Noscript support
|
| 66 |
|
| 67 | To make sure your elements are scrollable when JavaScript is disabled, it's important to include this snippet in your `<head>` to reset scrolling:
|
| 68 |
|
| 69 | ```js
|
| 70 | <noscript>
|
| 71 | <style>
|
| 72 | /**
|
| 73 | * Reinstate scrolling for non-JS clients
|
| 74 | */
|
| 75 | .simplebar-content-wrapper {
|
| 76 | scrollbar-width: auto;
|
| 77 | -ms-overflow-style: auto;
|
| 78 | }
|
| 79 |
|
| 80 | .simplebar-content-wrapper::-webkit-scrollbar,
|
| 81 | .simplebar-hide-scrollbar::-webkit-scrollbar {
|
| 82 | display: initial;
|
| 83 | width: initial;
|
| 84 | height: initial;
|
| 85 | }
|
| 86 | </style>
|
| 87 | </noscript>
|
| 88 | ```
|
| 89 |
|
| 90 | ### :warning: Warning!
|
| 91 |
|
| 92 | 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!**
|
| 93 |
|
| 94 | ### Troubleshooting
|
| 95 |
|
| 96 | 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.**
|
| 97 |
|
| 98 | ### Sponsors
|
| 99 |
|
| 100 | Thanks to BrowserStack for sponsoring open source projects and letting us test SimpleBar for free.
|
| 101 | <a href="https://www.browserstack.com" target="_blank">
|
| 102 | <img src="https://user-images.githubusercontent.com/15015324/45184727-368fbf80-b1fe-11e8-8827-08dbc80b0fb1.png" width="200">
|
| 103 | </a>
|
| 104 |
|
| 105 | ---
|
| 106 |
|
| 107 | 1. [Documentation](#1-documentation)
|
| 108 | 2. [Browsers support](#2-browsers-support)
|
| 109 | 3. [Demo](#3-demo)
|
| 110 | 4. [How it works](#4-how-it-works)
|
| 111 | 5. [Caveats](#5-caveats)
|
| 112 | 6. [Changelog](#6-changelog)
|
| 113 | 7. [Credits](#7-credits)
|
| 114 |
|
| 115 | ## 1. Documentation
|
| 116 |
|
| 117 | ### Other usages
|
| 118 |
|
| 119 | You can start SimpleBar manually if you need to:
|
| 120 |
|
| 121 | ```js
|
| 122 | new SimpleBar(document.getElementById('myElement'));
|
| 123 | ```
|
| 124 |
|
| 125 | or
|
| 126 |
|
| 127 | ```js
|
| 128 | Array.prototype.forEach.call(
|
| 129 | document.querySelectorAll('.myElements'),
|
| 130 | (el) => new SimpleBar(el)
|
| 131 | );
|
| 132 | ```
|
| 133 |
|
| 134 | If you want to use jQuery:
|
| 135 |
|
| 136 | ```js
|
| 137 | new SimpleBar($('#myElement')[0]);
|
| 138 | ```
|
| 139 |
|
| 140 | or
|
| 141 |
|
| 142 | ```js
|
| 143 | $('.myElements').each((el) => new SimpleBar(el));
|
| 144 | ```
|
| 145 |
|
| 146 | ### Styling
|
| 147 |
|
| 148 | 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.
|
| 149 |
|
| 150 | Ex, to change the color of the scrollbar:
|
| 151 |
|
| 152 | ```css
|
| 153 | .simplebar-scrollbar::before {
|
| 154 | background-color: red;
|
| 155 | }
|
| 156 | ```
|
| 157 |
|
| 158 | ### Options
|
| 159 |
|
| 160 | Options can be applied to the plugin during initialization:
|
| 161 |
|
| 162 | ```js
|
| 163 | new SimpleBar(document.getElementById('myElement'), {
|
| 164 | option1: value1,
|
| 165 | option2: value2,
|
| 166 | });
|
| 167 | ```
|
| 168 |
|
| 169 | or using data-attributes:
|
| 170 |
|
| 171 | ```html
|
| 172 | <div data-simplebar data-simplebar-auto-hide="false"></div>
|
| 173 | ```
|
| 174 |
|
| 175 | Available options are:
|
| 176 |
|
| 177 | #### autoHide
|
| 178 |
|
| 179 | 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`:
|
| 180 |
|
| 181 | ```js
|
| 182 | new SimpleBar(document.getElementById('myElement'), { autoHide: false });
|
| 183 | ```
|
| 184 |
|
| 185 | Default value is `true`.
|
| 186 |
|
| 187 | You can also control the animation via CSS as it's a simple CSS opacity transition.
|
| 188 |
|
| 189 | #### scrollbarMinSize
|
| 190 |
|
| 191 | Define the minimum scrollbar size in pixels.
|
| 192 |
|
| 193 | Default value is `10`.
|
| 194 |
|
| 195 | #### classNames
|
| 196 |
|
| 197 | 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.
|
| 198 |
|
| 199 | - `content` represents the wrapper for the content being scrolled.
|
| 200 | - `scrollContent` represents the container containing the elements being scrolled.
|
| 201 | - `scrollbar` defines the style of the scrollbar with which the user can interact to scroll the content.
|
| 202 | - `track` styles the area surrounding the `scrollbar`.
|
| 203 |
|
| 204 | ```js
|
| 205 | classNames: {
|
| 206 | // defaults
|
| 207 | content: 'simplebar-content',
|
| 208 | scrollContent: 'simplebar-scroll-content',
|
| 209 | scrollbar: 'simplebar-scrollbar',
|
| 210 | track: 'simplebar-track'
|
| 211 | }
|
| 212 | ```
|
| 213 |
|
| 214 | #### forceVisible
|
| 215 |
|
| 216 | You can force the track to be visible (same behaviour as `overflow: scroll`) using the `forceVisible` option:
|
| 217 |
|
| 218 | ```
|
| 219 | forceVisible: true|'x'|'y' (default to `false`)
|
| 220 | ```
|
| 221 |
|
| 222 | By default, SimpleBar behave like `overflow: auto`.
|
| 223 |
|
| 224 | #### direction (RTL support)
|
| 225 |
|
| 226 | You can activate RTL support by passing the `direction` option:
|
| 227 |
|
| 228 | ```
|
| 229 | direction: 'rtl' (default to `ltr`)
|
| 230 | ```
|
| 231 |
|
| 232 | You will need both `data-simplebar-direction='rtl'` and a css rule with `direction: rtl`.
|
| 233 |
|
| 234 | #### timeout (deprecated)
|
| 235 |
|
| 236 | This option is deprecated. You can now achieve this in CSS:
|
| 237 |
|
| 238 | ```
|
| 239 | .simplebar-scrollbar:before {
|
| 240 | transition-delay: 2s;
|
| 241 | }
|
| 242 | ```
|
| 243 |
|
| 244 | #### clickOnTrack
|
| 245 |
|
| 246 | Controls the click on track behaviour.
|
| 247 |
|
| 248 | Default to `true`.
|
| 249 |
|
| 250 | #### scrollbarMinSize / scrollbarMaxSize
|
| 251 |
|
| 252 | Controls the min and max size of the scrollbar in `px`.
|
| 253 |
|
| 254 | Default for `scrollbarMinSize` is `25`.
|
| 255 | Default for `scrollbarMaxSize` is `0` (no max size).
|
| 256 |
|
| 257 | ### Apply scroll vertically only
|
| 258 |
|
| 259 | Simply define in css `overflow-x: hidden` on your element.
|
| 260 |
|
| 261 | ### Notifying the plugin of content changes
|
| 262 |
|
| 263 | #### Note: you shouldn't need to use these functions as SimpleBar takes care of that automatically. This is for advanced usage only.
|
| 264 |
|
| 265 | If later on you dynamically modify your content, for instance changing its height or width, or adding or removing content, you should recalculate the scrollbars like so:
|
| 266 |
|
| 267 | ```js
|
| 268 | const simpleBar = new SimpleBar(document.getElementById('myElement'));
|
| 269 | simpleBar.recalculate();
|
| 270 | ```
|
| 271 |
|
| 272 | ### Trigger programmatical scrolling
|
| 273 |
|
| 274 | If you want to access to the original scroll element, you can retrieve it via a getter:
|
| 275 |
|
| 276 | ```js
|
| 277 | const simpleBar = new SimpleBar(document.getElementById('myElement'));
|
| 278 | simpleBar.getScrollElement();
|
| 279 | ```
|
| 280 |
|
| 281 | ### Subscribe to `scroll` event
|
| 282 |
|
| 283 | You can subscribe to the `scroll` event, just like you do with native scrolling elements:
|
| 284 |
|
| 285 | ```js
|
| 286 | const simpleBar = new SimpleBar(document.getElementById('myElement'));
|
| 287 | simpleBar.getScrollElement().addEventListener('scroll', function(...));
|
| 288 | ```
|
| 289 |
|
| 290 | ### Add content dynamically
|
| 291 |
|
| 292 | You can retrieve the element containing data like this:
|
| 293 |
|
| 294 | ```js
|
| 295 | const simpleBar = new SimpleBar(document.getElementById('myElement'));
|
| 296 | simpleBar.getContentElement();
|
| 297 | ```
|
| 298 |
|
| 299 | ### Disable Mutation Observer (core package only)
|
| 300 |
|
| 301 | ```js
|
| 302 | SimpleBar.removeObserver();
|
| 303 | ```
|
| 304 |
|
| 305 | ### Retrieve SimpleBar instance from data-simplebar nodes
|
| 306 |
|
| 307 | ```js
|
| 308 | SimpleBar.instances.get(document.querySelector('[data-simplebar]']))
|
| 309 | ```
|
| 310 |
|
| 311 | ### Non-JS fallback
|
| 312 |
|
| 313 | SimpleBar hides the browser's default scrollbars, which obviously is undesirable if the user has JavaScript disabled. To restore the browser's scrollbars you can include the following `noscript` element in your document's `head`:
|
| 314 |
|
| 315 | ```html
|
| 316 | <noscript>
|
| 317 | <style>
|
| 318 | [data-simplebar] {
|
| 319 | overflow: auto;
|
| 320 | }
|
| 321 | </style>
|
| 322 | </noscript>
|
| 323 | ```
|
| 324 |
|
| 325 | ## 2. Browsers support
|
| 326 |
|
| 327 | SimpleBar has been tested on the following browsers: Chrome, Firefox, Safari, Edge, IE11.
|
| 328 |
|
| 329 | Notice: IE10 doesn't support `MutationObserver` so you will still need to instantiate SimpleBar manually and call `recalculate()` as needed (or you can just use a polyfill for `MutationObserver`).
|
| 330 |
|
| 331 | If you want to apply SimpleBar on an SVG element on IE11, you will need a [polyfill for `classList`](https://github.com/eligrey/classList.js/blob/master/classList.js).
|
| 332 |
|
| 333 | IE9 is not supported anymore (because we use `translate3d` to position the scrollbar) so please use SimpleBar v1 if you really need it.
|
| 334 |
|
| 335 | ## 3. Demo
|
| 336 |
|
| 337 | https://grsmto.github.io/simplebar/
|
| 338 |
|
| 339 | ## 4. How it works
|
| 340 |
|
| 341 | SimpleBar only does one thing: replace the browser's default scrollbars with a custom CSS-styled scrollbar without sacrificing performance. Unlike most other plugins, SimpleBar doesn't mimic scroll behaviour with Javascript, which typically causes jank and strange scrolling behaviour. You keep the awesomeness of native scrolling… with a custom scrollbar!
|
| 342 | Design your scrollbar how you like, with CSS, across all browsers.
|
| 343 |
|
| 344 | For the most part SimpleBar uses the browser's native scrolling functionality, but replaces the conventional scrollbar with a custom CSS-styled scrollbar. The plugin listens for scroll events and redraws the custom scrollbar accordingly.
|
| 345 |
|
| 346 | Key to this technique is hiding the native browser scrollbar. The scrollable element is made slightly wider/taller than its containing element, effectively hiding the scrollbar from view.
|
| 347 |
|
| 348 | ## 5. Caveats
|
| 349 |
|
| 350 | - SimpleBar can't be used on the `<body>`, `<textarea>`, `<table>` or `<iframe>` elements. If you are looking to support these, I suggest taking a look at [OverLayScrollbars](https://kingsora.github.io/OverlayScrollbars).
|
| 351 | - SimpleBar doesn't currently support `overflow: visible`. Which means any children of your scrolling div will be clipped (like with `overflow: hidden`).
|
| 352 |
|
| 353 | Please take a look at [this comparison table](https://kingsora.github.io/OverlayScrollbars/#!faq) to see what SimpleBar does compare to others.
|
| 354 |
|
| 355 | ### Community plugins
|
| 356 |
|
| 357 | **Ruby On Rails**
|
| 358 | To include SimpleBar in the Ruby On Rails asset pipeline, use the [simplebar-rails](https://github.com/thutterer/simplebar-rails) gem.
|
| 359 |
|
| 360 | **Ember.js**
|
| 361 | To use SimpleBar with the Ember.js framework, use the [ember-simplebars](https://github.com/fpauser/ember-simplebar) addon.
|
| 362 |
|
| 363 | [npm-badge]: https://img.shields.io/npm/v/simplebar.svg?style=flat-square
|
| 364 | [npm]: https://www.npmjs.org/package/simplebar
|
| 365 | [size-badge]: http://img.badgesize.io/Grsmto/simplebar/master/packages/simplebar/src/simplebar.js?compression=gzip&&style=flat-square
|