\n\n---\n\n- Native browser scroll behavior - it don't emulate scrolling, only showing custom scrollbars,\n scrolling itself still native\n- Cross-browser and cross-platform - does not matter where and how, scrollbars looks the same\n everywhere\n- Ultimate performance - 60 FPS (using RAF) and highly optimised code\n- No extra stylesheets required - minimum inline styles out of the box or you can style it yourself\n however you want\n- Fully customizable - want a hippo as a scrollbar thumb? Well.. I don't judge you, you're free to\n do it!\n- Scrollbars nesting\n- Total tests coverage\n- Momentum scrolling for iOS\n- RTL support ([read more](#rtl-support))\n- Content sizes translation ([read more](#content-sizes-translation))\n- Proper page zoom handling (native scrollbars does not show up)\n\n## INSTALLATION\n\n```bash\nnpm install react-scrollbars-custom\n# or via yarn\nyarn add react-scrollbars-custom\n```\n\n**INSTALLATION NOTE:** \nThis lib is written in ES6+ and delivering with both, transpiled and untranspiled versions:\n\n- `main` field of `package.json` is pointing to transpiled ES3-compatible version with CJS modules\n resolution;\n- `module` field is pointing to transpiled ES3-compatible version with ES modules resolution;\n- `esnext` field is pointing to the ES6+ version with ES modules resolution;\n\nDepending on your targets you may have to use [Webpack](https://webpack.js.org/) and/or\n[Babel](http://babeljs.io/) to pull untranspiled version of package. \nSee some tips on wiring thing\nup: [https://2ality.com/2017/06/pkg-esnext.html](https://2ality.com/2017/06/pkg-esnext.html)\n\n## USAGE\n\nUnderneath `react-scrollbars-custom` uses `requestAnimationFrame` loop, which check and update each\nknown scrollbar, and as result - scrollbars updates synchronised with browser's render flow.\nThe `` component works out of the box, with only need of `width` and `height` to be\nset, inline or via CSS;\n\n```typescript jsx\nimport { Scrollbar } from 'react-scrollbars-custom';\n\n\n
Hello world!
\n;\n```\n\n### Internet Explorer\n\n`react-scrollbars-custom` is syntax-compatible with IE10, but you'll have to use polyfills - for\nexample [@babel/polyfill](https://babeljs.io/docs/en/babel-polyfill).\n\n#### Styling\n\nProbably you'll wish to customize your scrollbars on your own way via CSS - then simply\npass `noDefaultStyles` prop - it will prevent all inline styling from appear. \nBut some of styles will remain due to their need for proper component work.\n\n#### Native mode\n\nOne more pretty common need is to disable custom scrollbars and fallback to native ones, it can be\ndone by passing `native` prop.\nIt'll change the generated markup:\n\n```html\n// scrollbar.scrollerElement\n
\n // scrollbar.contentElement - the one that holds tour content\n
// YOUR CONTENT IS HERE
\n
\n```\n\nAs you see here - now the root element has the `scrollerElement` ref, but otherwise its treated as a\nbefore (as holder). `contentElement` behaves as it was before.\n\n#### Content sizes translation\n\nIn some situations you may want to make the scrollbars block of variable sizes - just\npass `translateContentSize*ToHolder` prop and component will automatically translate\ncorresponding `contentElement`'s sizes to the `holderElement`. \nIf you are using default styles - it'll be handy to pass `disableTracksWidthCompensation` props, to\navoid infinite shrinking when it's not supposed to. \n_Note:_ This wont work for native mode.\n\n#### RTL support\n\n`react-scrollbars-custom` supports RTL direction out of the box, you don't have to pass extra\nparameters to make it work, it'll be detected automatically on first component's render. But you\nstill able to override it through the prop.\nThere are several things you have to know about:\n\n- Due to performance reasons direction autodetect happens is 3 cases:\n - On component mount;\n - On rtl property change;\n - On state `isRtl` set to non-boolean value;\n- `rtl` property has priority over the `style` or CSS properties;\n- If `rtl` prop has not been set (undefined) - direction will be detected automatically according to\n content element's CSS;\n- If `rtl` prop is `true` - `direction: rtl;` style will be applied to hte content element;\n- If `rtl` prop is `false` - no style will be applied to holder;\n\n## Customization\n\nIn some cases you may want to change the default className or tagName of elements or add extra\nmarkup or whatever. For these purposes `react-scrollbars-custom` made fully customizable.\nYou can do absolutely what ever you want y simply passing renderer SFC to the needed props.\n\n> **IMPORTANT**: Renderer will receive elementRef function that expect the DOM element's reference\n> as first parameter. \n> Furthermore you have to pass the styles, cause they needed to proper component work.\n\n```typescript jsx\n {\n const { elementRef, ...restProps } = props;\n return ;\n }}\n wrapperProps={{\n renderer: (props) => {\n const { elementRef, ...restProps } = props;\n return ;\n },\n }}\n scrollerProps={{\n renderer: (props) => {\n const { elementRef, ...restProps } = props;\n return ;\n },\n }}\n contentProps={{\n renderer: (props) => {\n const { elementRef, ...restProps } = props;\n return ;\n },\n }}\n trackXProps={{\n renderer: (props) => {\n const { elementRef, ...restProps } = props;\n return ;\n },\n }}\n trackYProps={{\n renderer: (props) => {\n const { elementRef, ...restProps } = props;\n return ;\n },\n }}\n thumbXProps={{\n renderer: (props) => {\n const { elementRef, ...restProps } = props;\n return ;\n },\n }}\n thumbYProps={{\n renderer: (props) => {\n const { elementRef, ...restProps } = props;\n return ;\n },\n }}\n/>\n```\n\n#### Generated HTML\n\n```html\n// scrollbar.holderElement\n
\n // scrollbar.wrapperElement - the one that hiding native scrollbars\n
\n // scrollbar.scrollerElement - the one that actually has browser's scrollbars\n
\n // scrollbar.contentElement - the one that holds tour content\n
// YOUR CONTENT IS HERE
\n
\n
\n // scrollbar.trackYElement\n
\n // scrollbar.thumbYElement\n \n
\n // scrollbar.trackXElement\n
\n // scrollbar.thumbXElement\n \n
\n
\n```\n\n- If scrolling is possible or tracks are shown die to `permanentScrollbar*` prop - `trackYVisible`\n /`trackXVisible` classnames are applied to the holder element.\n- When thumb is dragged it'll have `dragging` classname.\n- If direction is RTL - `rtl` classname will be added to the holder element.\n- By default whole structure described above is rendered in spite of tracks visibility, but it can\n be changed by passing `removeTrackXWhenNotUsed`/`removeTrackYWhenNotUsed`\n /`removeTracksWhenNotUsed` props to the component. Respective tracks will not be rendered if it is\n unnecessary.\n\n## API\n\n### PROPS\n\nYou can pass any HTMLDivElement props to the component - they'll be respectfully passed to the\nholder element/renderer.\n\n**createContext** _`:boolean`_ = undefined \nWhether to create context that will contain scrollbar instance reference.\n\n**rtl** _`:boolean`_ = undefined \n`true` - set content's direction RTL, `false` - LTR, `undefined` - autodetect according content's\nstyle.\n\n**native** _`:boolean`_ = undefined \nDo not use custom scrollbars, use native ones instead.\n\n**mobileNative** _`:boolean`_ = undefined \nAs `native` but enables only on mobile devices (actually when the `scrollbarWidth` is 0).\n\n**momentum** _`:boolean`_ = true \nWhether to use momentum scrolling, suitable for iOS (will add `-webkit-overflow-scrolling: touch` to\nthe content element).\n\n**noDefaultStyles** _`:boolean`_ = undefined \nWhether to use default visual styles. \n_Note:_ Styles needed to proper component work will be passed regardless of this option.\n\n**disableTracksMousewheelScrolling** _`:boolean`_ = undefined \nDisable content scrolling while preforming a wheel event over the track.\n\n**disableTrackXMousewheelScrolling** _`:boolean`_ = undefined \nDisable content scrolling while preforming a wheel event over the track.\n\n**disableTrackYMousewheelScrolling** _`:boolean`_ = undefined \nDisable content scrolling while preforming a wheel event over the track.\n\n**disableTracksWidthCompensation** _`:boolean`_ = undefined \nDisable both vertical and horizontal wrapper indents that added in order to not let tracks overlay\ncontent.\n_Note:_ Works only with default styles enabled.\n\n**disableTrackXWidthCompensation** _`:boolean`_ = undefined \nDisable horizontal wrapper indents that added in order to not let horizontal track overlay content.\n_Note:_ Works only with default styles enabled.\n\n**disableTrackYWidthCompensation** _`:boolean`_ = undefined \nDisable vertical wrapper indents that added in order to not let vertical track overlay content.\n_Note:_ Works only with default styles enabled.\n\n**minimalThumbSize** _`:number`_ = 30 \nMinimal size of both, vertical and horizontal thumbs. This option has priority\nto `minimalThumbXSize`/`minimalThumbYSize` props.\n\n**maximalThumbSize** _`:number`_ = undefined \nMaximal size of both, vertical and horizontal thumbs. This option has priority\nto `maximalThumbXSize`/`maximalThumbYSize` props.\n\n**minimalThumbXSize** _`:number`_ = undefined \nMinimal size of horizontal thumb.\n\n**maximalThumbXSize** _`:number`_ = undefined \nMaximal size of horizontal thumb.\n\n**minimalThumbYSize** _`:number`_ = undefined \nMinimal size of vertical thumb.\n\n**maximalThumbYSize** _`:number`_ = undefined \nMaximal size of vertical thumb.\n\n**noScroll** _`:boolean`_ = undefined \nWhether to disable both vertical and horizontal scrolling.\n\n**noScrollX** _`:boolean`_ = undefined \nWhether to disable horizontal scrolling.\n\n**noScrollY** _`:boolean`_ = undefined \nWhether to disable vertical scrolling.\n\n**permanentTracks** _`:boolean`_ = undefined \nWhether to display both tracks regardless of scrolling ability.\n\n**permanentTrackX** _`:boolean`_ = undefined \nWhether to display horizontal track regardless of scrolling ability.\n\n**permanentTrackY** _`:boolean`_ = undefined \nWhether to display vertical track regardless of scrolling ability.\n\n**removeTracksWhenNotUsed** _`:boolean`_ = undefined \nWhether to remove both vertical and horizontal tracks if scrolling is not possible/blocked and\ntracks are not permanent.\n\n**removeTrackYWhenNotUsed** _`:boolean`_ = undefined \nWhether to remove vertical track if scrolling is not possible/blocked and tracks are not permanent.\n\n**removeTrackXWhenNotUsed** _`:boolean`_ = undefined \nWhether to remove horizontal track if scrolling is not possible/blocked and tracks are not\npermanent.\n\n**translateContentSizesToHolder** _`:boolean`_ = undefined \nPass content's `scrollHeight` and `scrollWidth` values to the holder's `height` and `width`\nstyles. _Not working with `native` behavior._\n\n**translateContentSizeYToHolder** _`:boolean`_ = undefined \nPass content's `scrollHeight` values to the holder's `height` style. _Not working with `native`\nbehavior._\n\n**translateContentSizeXToHolder** _`:boolean`_ = undefined \nPass content's `scrollWidth` values to the holder's `width` style. _Not working with `native`\nbehavior._\n\n**trackClickBehavior** _`:string`_ = \"jump\" \nThe way scrolling behaves while user clicked the track:\n\n- _jump_ - will cause straight scroll to the respective position.\n- _step_ - will cause one screen step towards (like PageUp/PageDown) the clicked position.\n\n**scrollbarWidth** _`:number`_ = undefined \nScrollbar width value needed to proper native scrollbars hide. While `undefined` it is detected\nautomatically (once per module require). \nThis prop is needed generally for testing purposes.\n\n**fallbackScrollbarWidth** _`:number`_ = 20 \nThis value will be used in case of falsy `scrollbarWidth` prop. E.g. it is used for mobile devices,\nbecause it is impossible to detect their real scrollbar width (due to their absolute positioning).\n\n**scrollTop** _`:number`_ = undefined \nProp that allow you to set vertical scroll.\n\n**scrollLeft** _`:number`_ = undefined \nProp that allow you to set horizontal scroll.\n\n**scrollDetectionThreshold** _`:number`_ = 100 \nAmount of seconds after which scrolling will be treated as completed and `scrollStop` event emitted.\n\n**elementRef** _`:function(ref: Scrollbar)`_ = undefined \nFunction that receive the scrollbar instance as 1st parameter.\n\n**renderer** _`:SFC`_ = undefined \nSFC used to render the holder. [More about renderers usage](#customisation).\n\n**wrapperProps** _`:object`_ = {} \nHere you can pass any props for wrapper, which is usually HTMLDivElement plus `elementRef` props\nwhich behaves as holder's `elementRef` prop.\n\n**contentProps** _`:object`_ = {} \nHere you can pass any props for content, which is usually HTMLDivElement plus `elementRef` props\nwhich behaves as holder's `elementRef` prop.\n\n**trackXProps** _`:object`_ = {} \nHere you can pass any props for trackX, which is usually HTMLDivElement plus `elementRef` props\nwhich behaves as holder's `elementRef` prop.\n\n**trackYProps** _`:object`_ = {} \nHere you can pass any props for trackY, which is usually HTMLDivElement plus `elementRef` props\nwhich behaves as holder's `elementRef` prop.\n\n**thumbXProps** _`:object`_ = {} \nHere you can pass any props for thumbX, which is usually HTMLDivElement plus `elementRef` props\nwhich behaves as holder's `elementRef` prop.\n\n**thumbYProps** _`:object`_ = {} \nHere you can pass any props for thumbY, which is usually HTMLDivElement plus `elementRef` props\nwhich behaves as holder's `elementRef` prop.\n\n**onUpdate** _`:function(scrollValues: ScrollState, prevScrollValues: ScrollState)`_ = undefined \nFunction called each time any of scroll values changed and component performed an update. It is\ncalled after component's update.\n\n**onScroll** _`:function(scrollValues: ScrollState, prevScrollValues: ScrollState)`_ = undefined \nFunction called each time scrollTop or scrollLeft has changed. It is called after component's update\nand even if scrollTop/scrollLeft has been changed through the code (not by user).\n\n**onScrollStart** _`:function(scrollValues: ScrollState)`_ = undefined \nCallback that called immediately when user started scrolling (no matter how, thumb dragging,\nkeyboard, mousewheel and etc.).\n\n**onScrollStop** _`:function(scrollValues: ScrollState)`_ = undefined\nCallback that called after `props.scrollDetectionThreshold` milliseconds after last scroll event.\n\n### INSTANCE PROPERTIES\n\n**eventEmitter** _`:Emittr`_ \nEvent emitter that allow you to add events handler for cases when you access Scrollbars through\ncontext\n\n**holderElement** _`:HTMLDivElement | null`_ \nHolder DOM element reference or null if element was not rendered\n\n**wrapperElement** _`:HTMLDivElement | null`_ \nWrapper DOM element reference or null if element was not rendered\n\n**scrollerElement** _`:HTMLDivElement | null`_ \nScroller DOM element reference or null if element was not rendered\n\n**contentElement** _`:HTMLDivElement | null`_ \nContent DOM element reference or null if element was not rendered\n\n**trackXElement** _`:HTMLDivElement | null`_ \nHorizontal track DOM element reference or null if element was not rendered\n\n**trackYElement** _`:HTMLDivElement | null`_ \nVertical track DOM element reference or null if element was not rendered\n\n**thumbXElement** _`:HTMLDivElement | null`_ \nHorizontal thumb DOM element reference or null if element was not rendered\n\n**thumbYElement** _`:HTMLDivElement | null`_ \nVertical thumb DOM element reference or null if element was not rendered\n\n(get|set) **scrollTop** _`:number`_ \nContent's element scroll top\n\n(get|set) **scrollLeft** _`:number`_ \nContent's element scroll left\n\n(get) **scrollHeight** _`:number`_ \nContent's element scroll height\n\n(get) **scrollWidth** _`:number`_ \nContent's element scroll width\n\n(get) **clientHeight** _`:number`_ \nContent's element client height\n\n(get) **clientWidth** _`:number`_ \nContent's element client width\n\n### INSTANCE METHODS\n\n**getScrollState(force:boolean = false)** _`:plain object`_\nCurrent scroll-related values, if `force` parameter is falsy - returns cached value which updated\nwith RAF loop\nReturned values:\n\n```typescript\ntype ScrollState = {\n /**\n * @description Content's native clientHeight parameter\n */\n clientHeight: number;\n /**\n * @description Content's native clientWidth parameter\n */\n clientWidth: number;\n /**\n * @description Content's native scrollHeight parameter\n */\n scrollHeight: number;\n /**\n * @description Content's native scrollWidth parameter\n */\n scrollWidth: number;\n /**\n * @description Content's native scrollTop parameter\n */\n scrollTop: number;\n /**\n * @description Content's native scrollLeft parameter\n */\n scrollLeft: number;\n /**\n * @description Indicates whether vertical scroll blocked via properties\n */\n scrollYBlocked: boolean;\n /**\n * @description Indicates whether horizontal scroll blocked via properties\n */\n scrollXBlocked: boolean;\n /**\n * @description Indicates whether the content overflows vertically and scrolling not blocked\n */\n scrollYPossible: boolean;\n /**\n * @description Indicates whether the content overflows horizontally and scrolling not blocked\n */\n scrollXPossible: boolean;\n /**\n * @description Indicates whether vertical track is visible\n */\n trackYVisible: boolean;\n /**\n * @description Indicates whether horizontal track is visible\n */\n trackXVisible: boolean;\n /**\n * @description Indicates whether display direction is right-to-left\n */\n isRTL?: boolean;\n\n /**\n * @description Pages zoom level - it affects scrollbars\n */\n zoomLevel: number;\n};\n```\n\n**scrollToTop()** _`:this`_ \nScroll to the very top border of scrollable area\n\n**scrollToLeft()** _`:this`_ \nScroll to the very left border of scrollable area\n\n**scrollToBottom()** _`:this`_ \nScroll to the very bottom border of scrollable area\n\n**scrollToRight()** _`:this`_ \nScroll to the very right border of scrollable area\n\n**scrollTo(x?: number, y?: number)** _`:this`_ \nSet the current scroll at given coordinates. If any value is `undefined` it'll be left as is.\n\n**centerAt(x?: number, y?: number)** _`:this`_ \nCenter viewport at given coordinates. If any value is `undefined` it'll be left as is.\n","readmeFilename":"README.md"}