# OverlayScrollbars for React
This is the official OverlayScrollbars React wrapper.
## Installation
```sh
npm install overlayscrollbars-react
```
## Peer Dependencies
OverlayScrollbars for React has the following **peer dependencies**:
- The vanilla JavaScript library: [overlayscrollbars](https://www.npmjs.com/package/overlayscrollbars)
```
npm install overlayscrollbars
```
- The React framework: [react](https://www.npmjs.com/package/react)
```
npm install react
```
## Usage
The first step is to import the CSS file into your app:
```ts
import 'overlayscrollbars/overlayscrollbars.css';
```
> __Note__: In older node versions use `'overlayscrollbars/styles/overlayscrollbars.css'` as the import path for the CSS file.
## Component
The main entry point is the `OverlayScrollbarsComponent` which can be used in your application as a component:
```jsx
import { OverlayScrollbarsComponent } from "overlayscrollbars-react";
// ...
example content
```
### Properties
The component accepts all properties of intrinsic JSX elements such as `div` and `span`.
Additionally it has three optional properties: `element`, `options` and `events`.
- `element`: accepts a `string` which represents the tag of the root element.
- `options`: accepts an `object` which represents the OverlayScrollbars options.
- `events`: accepts an `object` which represents the OverlayScrollbars events.
> __Note__: None of the properties has to be memoized.
```jsx
// example usage
{ /* ... */ } }}
/>
```
### Ref
The `ref` of the `OverlayScrollbarsComponent` will give you an object with which you can access the OverlayScrollbars `instance` and the root `element` of the component.
The ref object has two properties:
- `instance`: a function which returns the OverlayScrollbars instance.
- `element`: a function which returns the root element.
## Hook
In case the `OverlayScrollbarsComponent` is not enough, you can also use the `useOverlayScrollbars` hook:
```jsx
import { useOverlayScrollbars } from "overlayscrollbars-react";
// example usage
const Component = () => {
const ref = useRef();
const [initialize, instance] = useOverlayScrollbars({ options, events });
useEffect(() => {
const osInstance = initialize(ref.current);
return () => osInstance.destroy();
}, [initialize]);
return
}
```
The hook is for advanced usage and lets you control the whole initialization process. This is useful if you want to integrate it with other plugins such as `react-window` or `react-virtualized`.
### Parameters
Parameters are optional and similar to the `OverlayScrollbarsComponent`.
Its an `object` with two optional properties:
- `options`: accepts an `object` which represents the OverlayScrollbars options.
- `events`: accepts an `object` which represents the OverlayScrollbars events.
### Return
The `useOverlayScrollbars` hook returns a `tuple` with two values:
- The first value is the `initialization` function, it takes one argument which is the `InitializationTarget` and returns the OverlayScrollbars instance.
- The second value is a function which returns the current OverlayScrollbars instance or `null` if not initialized.
> __Note__: The identity of both functions is stable and won't change, thus they can safely be used in any dependency array.
## License
MIT
