Research
Security News
Malicious npm Package Targets Solana Developers and Hijacks Funds
A malicious npm package targets Solana developers, rerouting funds in 2% of transactions to a hardcoded address.
By Socket Research Team - Dec 02, 2024
Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
simplebar
Advanced tools
What is simplebar?
SimpleBar is a custom scrollbar library that aims to provide a simple and lightweight solution for creating custom scrollbars that look consistent across different browsers and platforms. It allows you to style the scrollbar to match your application's design while maintaining native scrolling performance.
What are simplebar's main functionalities?
Custom Scrollbars
SimpleBar allows you to create custom scrollbars by adding a `data-simplebar` attribute to your HTML elements. This will replace the default scrollbar with a custom one that you can style using CSS.
<div data-simplebar style="max-height: 300px;">
Your content here
</div>Auto-Hiding Scrollbars
You can control the auto-hide behavior of the scrollbar by setting the `data-simplebar-auto-hide` attribute to `false`. This will keep the scrollbar visible at all times.
<div data-simplebar-auto-hide="false" style="max-height: 300px;">
Your content here
</div>RTL Support
SimpleBar supports right-to-left (RTL) text direction. You can enable this by setting the `data-simplebar-direction` attribute to `rtl`.
<div data-simplebar-direction="rtl" style="max-height: 300px;">
Your content here
</div>Custom Scrollbar Styles
You can customize the appearance of the scrollbar by targeting the `.simplebar-scrollbar` class in your CSS. This allows you to change the color, width, and other styles of the scrollbar.
<style>
.simplebar-scrollbar::before {
background-color: #3498db;
}
</style>
<div data-simplebar style="max-height: 300px;">
Your content here
</div>Other packages similar to simplebar
perfect-scrollbar
Perfect Scrollbar is a similar library that provides custom scrollbars with a focus on performance and simplicity. It offers more customization options and better support for touch devices compared to SimpleBar.
react-custom-scrollbars
React Custom Scrollbars is a React-specific library for creating custom scrollbars. It provides a more React-friendly API and better integration with React applications compared to SimpleBar.
SimpleBar 
:warning: SimpleBar v4.3 is here! There are some breaking changes! Make sure to check out the changelog 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 's Overlay Scrollbars.
Installation
- Via npm
npm install simplebar --save
- Via Yarn
yarn add simplebar
- Via <script> tag
<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.
Usage
Check out the React and Vue examples.
If you are using Gatsby, please see #345.
If you are using a module loader (like Webpack) you first need to load SimpleBar:
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.
<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:
<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 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.
1. Documentation
Other usages
You can start SimpleBar manually if you need to:
new SimpleBar(document.getElementById('myElement'));
or
Array.prototype.forEach.call(
document.querySelectorAll('.myElements'),
el => new SimpleBar()
);
If you want to use jQuery:
new SimpleBar($('#myElement')[0]);
or
$('.myElements').each(element, new SimpleBar());
Options
Options can be applied to the plugin during initialization:
new SimpleBar(document.getElementById('myElement'), {
option1: value1,
option2: value2
});
or using data-attributes:
<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:
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.
contentrepresents the wrapper for the content being scrolled.scrollContentrepresents the container containing the elements being scrolled.scrollbardefines the style of the scrollbar with which the user can interact to scroll the content.trackstyles the area surrounding thescrollbar.
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`)
By default, SimpleBar behave like overflow: auto.
direction (RTL support)
You can activate RTL support by passing the direction option:
direction: 'rtl' (default to `ltr`)
You will need both data-simplebar-direction='rtl' and a css rule with direction: rtl.
Apply scroll vertically only
Simply define in css overflow-x: hidden on your element.
Notifying the plugin of content changes
Note: you shouldn't need to use these functions as SimpleBar takes care of that automatically. This is for advanced usage only.
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:
const simpleBar = new SimpleBar(document.getElementById('myElement'));
simpleBar.recalculate();
Trigger programmatical scrolling
If you want to access to the original scroll element, you can retrieve it via a getter:
const simpleBar = new SimpleBar(document.getElementById('myElement'));
simpleBar.getScrollElement();
Subscribe to scroll event
You can subscribe to the scroll event, just like you do with native scrolling elements:
const simpleBar = new SimpleBar(document.getElementById('myElement'));
simpleBar.getScrollElement().addEventListener('scroll', function(...));
Add content dynamically
You can retrieve the element containing data like this:
const simpleBar = new SimpleBar(document.getElementById('myElement'));
simpleBar.getContentElement();
Disable Mutation Observer
SimpleBar.removeObserver();
Retrieve SimpleBar instance from data-simplebar nodes
SimpleBar.instances.get(document.querySelector('[data-simplebar]']))
Non-JS fallback
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:
<noscript>
<style>
[data-simplebar] {
overflow: auto;
}
</style>
</noscript>
2. Browsers support
SimpleBar has been tested on the following browsers: Chrome, Firefox, Safari, Edge, IE11.
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).
If you want to apply SimpleBar on an SVG element on IE11, you will need a polyfill for classList.
IE9 is not supported anymore (because we use translate3d to position the scrollbar) so please use SimpleBar v1 if you really need it.
3. Demo
https://grsmto.github.io/simplebar/
4. How it works
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! Design your scrollbar how you like, with CSS, across all browsers.
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.
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.
5. Caveats
- 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. - SimpleBar doesn't currently support
overflow: visible. Which means any children of your scrolling div will be clipped (like withoverflow: hidden).
Please take a look at this comparison table to see what SimpleBar does compare to others.
Community plugins
Ruby On Rails To include SimpleBar in the Ruby On Rails asset pipeline, use the simplebar-rails gem.
FAQs
Scrollbars, simpler.
The npm package simplebar receives a total of 422,671 weekly downloads. As such, simplebar popularity was classified as popular.
We found that simplebar demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Package last updated on 06 Nov 2019
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Related posts
Security News
Research
Typosquatting Cryptographic Libraries: Malicious npm Packages Threaten Crypto Developers with Keylogging and Wallet Theft
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
By Kirill Boychenko - Nov 27, 2024
Security News
Weekly Downloads Now Available in npm Package Search Results
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
By Sarah Gooding - Nov 26, 2024