# React Scrollbar
The Simplest Scroll Area Component with custom scrollbar for [React Js](http://facebook.github.io/react/). It's adopted from [reactScrollbar](https://github.com/souhe/reactScrollbar) but without any dependencies. All animation, Height and Width are pure CSS, So it's TOTALLY **CUSTOMIZABLE** and **RESPONSIVE**! YEAH!.
[DEMO](https://bosnaufal.github.io/react-scrollbar)
## Install
You can install it via NPM
```bash
npm install react-scrollbar-js --save
```
> **Note**: You don't need any other dependencies or webpack loaders to start using this package. You can even use it with the `ES5` sintax if you need. But all examples in this readme will be shown in the `ES6` sintax.
## Usage
```javascript
// scrollable-component.jsx:
import React from 'react';
import ReactDOM from 'react-dom';
import ReactScrollbar from 'react-scrollbar-js';
class ScrollableComponent extends React.Component {
render() {
const myScrollbar = {
width: 400,
height: 400,
};
return(
And Now
You Can Put
A Long Content Here
)
}
}
```
> **Note**: `react-scrollbar-js` ships with a good looking default appearance, so you don't need to add any css styles to start it working. Only you need is to pass dimensions via [css](#classname-string-optional) or [inline style](#style-object-optional). But you can simply [customize](#scrollbar-structure) it by importing your own css styles.
## Props
##### className (String) [optional]
Just the ordinary class name of the root scrollbar element (`div`). So, It's TOTALLY **CUSTOMIZABLE!**
> default value: `'react-scrollbar-default'`
You can set different class names in oder to have some scrollbars with a various appearance on same page.
```css
/*The Scrollbar Root*/
.react-scrollbar-default {
width: 35%;
min-width: 300px;
max-height: 450px;
}
/*The Content*/
.scroll-me {
min-width: 750px;
}
```
##### style (Object) [optional]
If you prefer to use inline style to styling the scrollbar root (`div` element), you can pass the styling object to this props.
> default value: `{ }`
```javascript
let styling = {
/* Scrollbar */
scrollbar: {
width: "35%",
minWidth: "300px",
maxHeight: "450px"
},
}
```
##### speed (Number) [optional]
The wheel step in pixel.
> default value: `53`
## API
##### scrollToY(y), scrollToX(x)
To scroll the scrollbar by vertical/horizontal
where `x` and `y` could be:
- numbers - sets scrollbar position in pixels
- strings like '58%' - sets scrollbar position in percents
if the value is negative it'll count from the end in the backward direction. ex:
- `scrollToY(150)` set vertical scroll to 150px from top
- `scrollToY(-150)` set vertical scroll to 150px from bottom
- `scrollToY('30%')` set vertical scroll to 30% from top
- `scrollToY('-30%')` same as `scrollToY('70%')`
if you pass the value that is bigger than the maximum size it will scroll to 100%.
```javascript
// in ScrollableComponent class:
scrollTo(pos) {
return () => {
this.scroll.scrollToY(pos);
// or: this.scroll.scrollToX(pos);
};
}
// in ScrollableComponent render():
...
{ this.scroll = c; }}>
...
```
## Customizing the appearance
You can add you own css styles to define the appearence and behavior of scrollbar. Scrollbar has a structure of nested elements wich defined by specific css classes. You need to follow this structure to apply your properties to the right place. Each element has a set of classes (the number is different depending on the current mode). In general it has name like: `-reactjs-scrollbar-element:modifier1:modifier2`. Modifiers are optional and specify a position or a interaction mode of element. For your convenience the elements has a range of classes with different combinations of modifiers, ex:
```javascript
-reactjs-scrollbar-track // for any scrollbar track in any state
-reactjs-scrollbar-track:vertical // for the vertical scrollbar track in any state
-reactjs-scrollbar-track:dragging // for any scrollbar track while dragging
-reactjs-scrollbar-track:vertical:dragging // for vertical scrollbar track while dragging
-reactjs-scrollbar-track:vertical:dragging:hover // ...and while mouse is over it
```
But oder of modifiers does matter, so you **can't** set `-reactjs-scrollbar-track:dragging:vertical`
*This class structure is inspired by [-webkit-scrollbar](https://css-tricks.com/custom-scrollbars-in-webkit/), but here it's pretty simplified*
##### Scrollbar structure
```javascript
react-scrollbar-default // The scrollbar root. You can set any className here
-reactjs-scrollbar-area // Scrollbar children and tracks are here
-reactjs-scrollbar-area:dragging // when it's dragging by mouse
-reactjs-scrollbar-area:scrolling // when it's scrolling by mouse wheel
scroll-content // it just a child element, you can set any className
-reactjs-scrollbar-track // vertical track
-reactjs-scrollbar-track:vertical:dragging // you can use one of them or bouth
-reactjs-scrollbar-thumb // thumb on vertical track
-reactjs-scrollbar-thumb:vertical:dragging // you can use one of them or bouth
-reactjs-scrollbar-track // horizontal track
-reactjs-scrollbar-track:horizontal:dragging // you can use one of them or bouth
-reactjs-scrollbar-thumb // thumb on horizontal track
-reactjs-scrollbar-thumb:horizontal:dragging // you can use one of them or bouth
```
> You can add `:hover` or any pseudo class you need.
##### Style Applying
In oder to set custom style for your scrollbar add css styles to your page.
```js
// scrollable-component.jsx:
import './style_custom1.css';
// ScrollableComponent class:
...
...
```
```css
// style_custom1.css:
.react-scrollbar-default .-reactjs-scrollbar-thumb {
background: red;
cursor: default;
width: 10px;
height: 10px;
}
```
You can have some scrollbars with a different appearance. You can scope it by setting different root class names for them.
You can use the default style as a starting point for customizing:
[style_default.css](doc/examples/style_default.css)
[style_default.scss](doc/examples/style_default.scss)
## Examples
This repo has some example projects.
```shell
git clone https://github.com/BosNaufal/react-scrollbar.git
cd react-scrollbar-js/doc/examples/simple
# or
cd react-scrollbar-js/doc/examples/custom
npm i
npm start
```
open [localhost:8080](http://localhost:8080/) in your browser.
Simple example whit navigation API
It has scrollbar with default settings and some navigation buttons
Example of customizing scrollbars
It has scrollbars with different css styles.
## Contributing
Start from cloning this repo:
```shell
git clone https://github.com/BosNaufal/react-scrollbar.git
cd react-scrollbar-js
npm i
npm start
```
open [localhost:8080](http://localhost:8080/) in your browser.
You will see a demo app with a scrollbar area.
All source code of this package is located in `src/` folder and the demo app is in `develop/` (it's not included into this package).
We use `webpack-dev-server` for developing. It starts by `npm start`. The config file is `webpack.dev.config.js`.
We publish to NPM a compiled and bundled code, so it could be used in ES5 projects and don't have any dependencies. To prepare a library bundle we use `webpack` with the `webpack.publish.config.js` config file.
To publish it to NPM save all src files and type:
```
npm publish
```
this script automatically prepare dist folder for publishing and if there are no errors publish it to NPM.
You can check this process without publishing by typing:
```
npm run prepublish
```
it'll do the follow:
- checks src code with ESLint (`npm run lint`)
- builds the library package into `dist/` folder (`npm run build`)
- puts an actual copy of default style into `doc/examples` (`npm run getstyles`) *you need to push it to GitHub manually after that*
We use ESLint for code linting in this project. You can try to fix some common linting issues by typing `npm run lintfix`. It'll check the code only within `src/` folder.
We are welcome any issues or PR's to make this project better!
## Thank You for Making this useful~
## Let's talk about some projects with me
Just Contact Me At:
- Email: [bosnaufalemail@gmail.com](mailto:bosnaufalemail@gmail.com)
- Skype Id: bosnaufal254
- twitter: [@BosNaufal](https://twitter.com/BosNaufal)
## License
[MIT](http://opensource.org/licenses/MIT)
Copyright (c) 2016 - forever Naufal Rabbani