Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/rommguy/react-custom-scroll

Easily customize the browser scroll bar with native OS scroll behavior
https://github.com/rommguy/react-custom-scroll

css javascript reactjs

Last synced: about 1 month ago
JSON representation

Easily customize the browser scroll bar with native OS scroll behavior

Awesome Lists containing this project

README 

        
[![NPM version][npm-image]][npm-url]

![](https://github.com/rommguy/react-custom-scroll/workflows/build/badge.svg)

![](https://img.shields.io/npm/dw/react-custom-scroll)



# React-Custom-Scroll

An easily designable, cross browser (!!), custom scroll with ReactJS.    



The actual scroll is still the native one - Meaning the scroll animations and scroll rate work as always

The only thin that is different is the visible design and scrollbar layout. 



##### See a [working demo](http://rommguy.github.io/react-custom-scroll/exampleDist/index.html) ###

## Installation

```sh

npm i react-custom-scroll --save

```



### Why do I need this ?  

- Same design on all browsers

- Scrollbar is above the content instead of floating to the side - same layout on scrolled content as not scrolled content



### How to use ?

Custom scroll component is available in module or commonJS format.   

It is located in /dist directory       

**From unpkg cdn:**      

* [Js file](https://unpkg.com/[email protected]/dist/index.umd.js)



Wrap your content with the custom scroll component  

Remove any overflow style properties from your content root component - The custom scroll will take care of it



```js

import { CustomScroll } from "react-custom-scroll";

```



```jsx



  your content



```

  

### How to change the design ?  

Your own custom design can be applied by styling these 2 classes in your css:  



- rcs-custom-scrollbar - this class styles the container of the scroll handle, you can use it if your handle width is greater than the default.  

- rcs-inner-handle - this class styles the handle itself, you can use it to change the color, background, border and such of the handle  



You can see a usage example in the demo page.  



### Options (react props)



- **allowOuterScroll** : boolean, default false. Blocks outer scroll while scrolling the content

- **heightRelativeToParent** : string, default undefined. Content height limit is relative to parent - the value should be the height limit.

- **flex** : number, default undefined. If present will apply to the content wrapped by the custom scroll.  

This prop represents flex size. It is only relevant if the parent of customScroll has display: flex. See example below.  

This prop will override any value given to heightRelativeToParent when setting the height of customScroll.

- **onScroll** - function, default undefined. Listener that will be called on each scroll.

- **addScrolledClass** : boolean, default false. If true, will add a css class 'content-scrolled' while being scrolled.

- **freezePosition** : boolean, default false. When true, will prevent scrolling. 

- **minScrollHandleHeight** : number, sets the mimimum height of the scroll handle. Default is 38, as in Chrome on OSX.

- **rtl** : boolean, default false. Right to left document, will place the custom scrollbar on the left side of the content, and assume the native one is also there.

- **scrollTo**: number, default undefined. Will scroll content to the given value.

- **keepAtBottom**: boolean, default false. For dynamic content, will keep the scroll position at the bottom of the content, when the content changes, if the position was at the bottom before the change. [See example here](http://rommguy.github.io/react-custom-scroll/exampleDist/index.html#dynamic-content-example)

- **className**: string, default undefined. Allows adding your own class name to the root element.

- **handleClass**: string. Can be used to replace the className given to the scroll handle, which is 'rcs-inner-handle' by default.



##### Example for heightRelativeToParent



```jsx



  your content

  

```



### It doesn't work, please help me



- Check if you forgot to remove 'overflow' properties from the content root element.

- If you're using JSX, make sure you use Pascal case and not camelCase \ and not \.  

starting with lower case causes JSX to treat the tag as a native dom element

- Make sure you have a height limit on the content root element (max-height)

- Check if your height limit is relative to parent, and you didn't use heightRelativeToParent prop.



### Typescript

- You can use CustomScroll types by installing @types/react-custom-scroll from npm



### Usage with flexbox

##### See a [demo with Flex](http://rommguy.github.io/react-custom-scroll/exampleDist/index.html#flex-example) ###

There are some details that apply when using customScroll on elements with size set by css flex.  

Here is an example for an HTML structure before using customScroll:  



```jsx



  

  

    your content (with enough height to cause a scroll)

  

  

```



In this example, a scroll is active on the flexibleHeightElement, where the flex size sets it's height to 400px, after the fixedHeight element took 100px.  



#### Solutions

There are 2 options to use customScroll with this structure:



- Wrapping the content:  

For this solution, the overflow property should be removed from the flex size element, since the customScroll will take care of that. 

Instead, min-height and min-width should be set to 0.



```jsx



  

  

    

      your content (with enough height to cause a scroll)

    

  

  

```



min-height and min-width are required since flex won't shrink below it's minimum content size ([flex box spec](https://www.w3.org/TR/css-flexbox/#flex-common)).  



- Replacing the flex-size element with customScroll



```jsx



  

  

      your content (with enough height to cause a scroll)

  

  

```



### Contributing

This project is built using Vite.

To run in dev mode - "yarn dev" or "npm run dev".

To build the project - "yarn build" or "npm run build". 



### Tests

```sh

npm install

npm test

# Or for continuous run

npx karma start

```



[npm-image]: https://img.shields.io/npm/v/react-custom-scroll.svg?style=flat-square

[npm-url]: https://npmjs.org/package/react-custom-scroll

[travis-image]: https://img.shields.io/travis/wix/react-custom-scroll/main.svg?style=flat-square

[travis-url]: https://travis-ci.org/wix/react-custom-scroll

[coveralls-image]: https://img.shields.io/coveralls/wix/react-custom-scroll/main.svg?style=flat-square

[coveralls-url]: https://coveralls.io/r/wix/react-custom-scroll?branch=gh-pages

[downloads-image]: http://img.shields.io/npm/dm/react-custom-scroll.svg?style=flat-square

[downloads-url]: https://npmjs.org/package/react-custom-scroll