{"id":13421975,"url":"https://github.com/rommguy/react-custom-scroll","last_synced_at":"2025-05-15T11:00:22.007Z","repository":{"id":30222017,"uuid":"33773078","full_name":"rommguy/react-custom-scroll","owner":"rommguy","description":"Easily customize the browser scroll bar with native OS scroll behavior","archived":false,"fork":false,"pushed_at":"2025-02-22T10:09:11.000Z","size":2958,"stargazers_count":561,"open_issues_count":19,"forks_count":64,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-05-11T03:06:39.862Z","etag":null,"topics":["css","javascript","reactjs"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rommguy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"rommguy"}},"created_at":"2015-04-11T11:17:16.000Z","updated_at":"2025-04-30T07:26:12.000Z","dependencies_parsed_at":"2024-04-17T11:36:36.299Z","dependency_job_id":"2fbf3202-0678-4a6b-934d-b85c1ff8bed6","html_url":"https://github.com/rommguy/react-custom-scroll","commit_stats":{"total_commits":352,"total_committers":20,"mean_commits":17.6,"dds":0.5255681818181819,"last_synced_commit":"86422ff1633d235d42e03a37ca8a86cc433dc349"},"previous_names":[],"tags_count":52,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rommguy%2Freact-custom-scroll","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rommguy%2Freact-custom-scroll/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rommguy%2Freact-custom-scroll/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rommguy%2Freact-custom-scroll/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rommguy","download_url":"https://codeload.github.com/rommguy/react-custom-scroll/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254328384,"owners_count":22052632,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["css","javascript","reactjs"],"created_at":"2024-07-30T23:00:34.803Z","updated_at":"2025-05-15T11:00:21.975Z","avatar_url":"https://github.com/rommguy.png","language":"TypeScript","readme":"[![NPM version][npm-image]][npm-url]\n![](https://github.com/rommguy/react-custom-scroll/workflows/build/badge.svg)\n![](https://img.shields.io/npm/dw/react-custom-scroll)\n\n\n# React-Custom-Scroll\nAn easily designable, cross browser (!!), custom scroll with ReactJS.    \n\nThe actual scroll is still the native one - Meaning the scroll animations and scroll rate work as always\nThe only thin that is different is the visible design and scrollbar layout. \n\n##### See a [working demo](http://rommguy.github.io/react-custom-scroll/exampleDist/index.html) ###\n## Installation\n```sh\nnpm i react-custom-scroll --save\n```\n\n### Why do I need this ?  \n- Same design on all browsers\n- Scrollbar is above the content instead of floating to the side - same layout on scrolled content as not scrolled content\n\n### How to use ?\nCustom scroll component is available in module or commonJS format.   \nIt is located in /dist directory       \n**From unpkg cdn:**      \n* [Js file](https://unpkg.com/react-custom-scroll@7.0.0/dist/index.umd.js)\n\nWrap your content with the custom scroll component  \nRemove any overflow style properties from your content root component - The custom scroll will take care of it\n\n\n```js\nimport { CustomScroll } from \"react-custom-scroll\";\n```\n\n```jsx\n\u003cCustomScroll\u003e\n  your content\n\u003c/CustomScroll\u003e\n```\n  \n### How to change the design ?  \nYour own custom design can be applied by styling these 2 classes in your css:  \n\n- 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.  \n- rcs-inner-handle - this class styles the handle itself, you can use it to change the color, background, border and such of the handle  \n\nYou can see a usage example in the demo page.  \n\n### Options (react props)\n\n- **allowOuterScroll** : boolean, default false. Blocks outer scroll while scrolling the content\n- **heightRelativeToParent** : string, default undefined. Content height limit is relative to parent - the value should be the height limit.\n- **flex** : number, default undefined. If present will apply to the content wrapped by the custom scroll.  \nThis prop represents flex size. It is only relevant if the parent of customScroll has display: flex. See example below.  \nThis prop will override any value given to heightRelativeToParent when setting the height of customScroll.\n- **onScroll** - function, default undefined. Listener that will be called on each scroll.\n- **addScrolledClass** : boolean, default false. If true, will add a css class 'content-scrolled' while being scrolled.\n- **freezePosition** : boolean, default false. When true, will prevent scrolling. \n- **minScrollHandleHeight** : number, sets the mimimum height of the scroll handle. Default is 38, as in Chrome on OSX.\n- **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.\n- **scrollTo**: number, default undefined. Will scroll content to the given value.\n- **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)\n- **className**: string, default undefined. Allows adding your own class name to the root element.\n- **handleClass**: string. Can be used to replace the className given to the scroll handle, which is 'rcs-inner-handle' by default.\n\n##### Example for heightRelativeToParent\n\n```jsx\n\u003cCustomScroll heightRelativeToParent=\"calc(100% - 20px)\"\u003e\n  your content\n\u003c/CustomScroll\u003e  \n```\n\n### It doesn't work, please help me\n\n- Check if you forgot to remove 'overflow' properties from the content root element.\n- If you're using JSX, make sure you use Pascal case and not camelCase \\\u003cCustomScroll\\\u003e and not \\\u003ccustomScroll\\\u003e.  \nstarting with lower case causes JSX to treat the tag as a native dom element\n- Make sure you have a height limit on the content root element (max-height)\n- Check if your height limit is relative to parent, and you didn't use heightRelativeToParent prop.\n\n### Typescript\n- You can use CustomScroll types by installing @types/react-custom-scroll from npm\n\n### Usage with flexbox\n##### See a [demo with Flex](http://rommguy.github.io/react-custom-scroll/exampleDist/index.html#flex-example) ###\nThere are some details that apply when using customScroll on elements with size set by css flex.  \nHere is an example for an HTML structure before using customScroll:  \n\n```jsx\n\u003cSomeParent style=\"display: flex; height: 500px;\"\u003e\n  \u003cFixedHeightElement style=\"height: 100px\"\u003e\u003cFixedHeightElement /\u003e\n  \u003cFlexibleHeightElement style=\"flex:1; overflow:scroll\"\u003e\n    your content (with enough height to cause a scroll)\n  \u003cFlexibleHeightElement /\u003e\n\u003c/SomeParent\u003e  \n```\n\nIn 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.  \n\n#### Solutions\nThere are 2 options to use customScroll with this structure:\n\n- Wrapping the content:  \nFor this solution, the overflow property should be removed from the flex size element, since the customScroll will take care of that. \nInstead, min-height and min-width should be set to 0.\n\n```jsx\n\u003csomeParent style=\"display: flex; height: 500px;\"\u003e\n  \u003cfixedHeightElement style=\"height: 100px\"\u003e\u003cfixedHeightElement/\u003e\n  \u003cflexibleHeightElement style=\"flex:1; min-height: 0; min-width: 0\"\u003e\n    \u003cCustomScroll heightRelativeToParent=\"100%\"\u003e\n      your content (with enough height to cause a scroll)\n    \u003cCustomScroll/\u003e\n  \u003cflexibleHeightElement/\u003e\n\u003c/someParent\u003e  \n```\n\nmin-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)).  \n\n- Replacing the flex-size element with customScroll\n\n```jsx\n\u003csomeParent style=\"display: flex; height: 500px;\"\u003e\n  \u003cfixedHeightElement style=\"height: 100px\"\u003e\u003cfixedHeightElement/\u003e\n  \u003cCustomScroll flex=\"1\"\u003e\n      your content (with enough height to cause a scroll)\n  \u003cCustomScroll/\u003e\n\u003c/someParent\u003e  \n```\n\n### Contributing\nThis project is built using Vite.\nTo run in dev mode - \"yarn dev\" or \"npm run dev\".\nTo build the project - \"yarn build\" or \"npm run build\". \n\n### Tests\n```sh\nnpm install\nnpm test\n# Or for continuous run\nnpx karma start\n```\n\n[npm-image]: https://img.shields.io/npm/v/react-custom-scroll.svg?style=flat-square\n[npm-url]: https://npmjs.org/package/react-custom-scroll\n[travis-image]: https://img.shields.io/travis/wix/react-custom-scroll/main.svg?style=flat-square\n[travis-url]: https://travis-ci.org/wix/react-custom-scroll\n[coveralls-image]: https://img.shields.io/coveralls/wix/react-custom-scroll/main.svg?style=flat-square\n[coveralls-url]: https://coveralls.io/r/wix/react-custom-scroll?branch=gh-pages\n[downloads-image]: http://img.shields.io/npm/dm/react-custom-scroll.svg?style=flat-square\n[downloads-url]: https://npmjs.org/package/react-custom-scroll\n","funding_links":["https://github.com/sponsors/rommguy"],"categories":["UI Components","Uncategorized","TypeScript","Demos","\u003csummary\u003eUI Components\u003c/summary\u003e"],"sub_categories":["Custom Scrollbar","Uncategorized"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frommguy%2Freact-custom-scroll","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frommguy%2Freact-custom-scroll","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frommguy%2Freact-custom-scroll/lists"}