# ray-scrollbar

> scrollbar

Latest version **1.1.1** (published 2024-07-29) · MIT license · 0 weekly downloads

## Install

```sh
npm install ray-scrollbar
pnpm add ray-scrollbar
yarn add ray-scrollbar
bun add ray-scrollbar
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.1 |
| Published | 2024-07-29 |
| First published | 2018-01-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 63.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | ilex.h |
| Maintainers | ilex.h |
| Keywords | react, reactjs, scrollbar |

## Links

- npm: https://www.npmjs.com/package/ray-scrollbar
- npm.io page: https://npm.io/package/ray-scrollbar

## Dependencies (4)

- [dt2react](https://npm.io/package/dt2react.md) ^2.x
- [ray-tween](https://npm.io/package/ray-tween.md) ^1.x
- [classnames](https://npm.io/package/classnames.md) ^2.2.6
- [prop-types](https://npm.io/package/prop-types.md) ^15.6.1

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 1.1.1 (latest) — 2024-07-29
- 1.1.0 — 2024-03-05
- 1.0.6 — 2021-12-08
- 1.0.5 — 2021-05-18
- 1.0.4 — 2021-02-02
- 1.0.3 — 2020-04-28
- 1.0.2 — 2020-04-27
- 1.0.1 — 2018-09-04
- 1.0.0 — 2018-01-05

## README

# ray-scrolbar

## Install

```bash
npm install ray-scrolbar --save
```

## Scrollbars

### Scrollbars usage

```js
import Scrollbars from 'ray-scrolbar';
```

The `<Scrollbars>` component works out of the box with some default styles. The only thing you need to care about is that the component has a `width` and `height`:

```js
import Scrollbars from 'ray-scrolbar';

class App extends Component {
  render() {
    return (
      <Scrollbars style={{ width: 500, height: 300 }}>
        <p>Some large content...</p>
      </Scrollbars>
    );
  }
}
```

The `<Scrollbars>` component is completely customizable. Check out the following code:

```js
import Scrollbars from 'ray-scrolbar';

class CustomScrollbars extends Component {
  render() {
    return (
      <Scrollbars
        onScroll={this.handleScroll}
        onScrollFrame={this.handleScrollFrame}
        onScrollStart={this.handleScrollStart}
        onScrollStop={this.handleScrollStop}
        onUpdate={this.handleUpdate}
        renderView={this.renderView}
        renderHorizontalTrack={this.renderHorizontalTrack}
        renderVerticalTrack={this.renderVerticalTrack}
        renderHorizontalThumb={this.renderHorizontalThumb}
        renderVerticalThumb={this.renderVerticalThumb}
        autoHide
        autoHideTimeout={1000}
        autoHideDuration={200}
        autoHeight
        autoHeightMin={0}
        autoHeightMax={200}
        thumbMinSize={30}
        universal={true}
        {...this.props}>
    );
  }
}
```

### Scrollbars props

| params| type | default | description |
| ------ | ------ | ------ | ------ |
| onScroll | `func: (event) => {}` | - | Event handler |
| onScrollFrame | func: (values: [Values](#Values)) => {} | - |  Runs inside the animation frame. |
| onScrollStart | `func: (event) => {}` | - | Called when scrolling starts |
| onScrollStop | `func: (event) => {}` | - | Called when scrolling stops |
| onUpdate | func: (values: [Values](#Values)) => {} | - | Called when ever the component is updated. Runs inside the animation frame |
| renderView | `func: () => JSX.Element` | - | The element your content will be rendered in |
| renderHorizontalTrack | `func: () => JSX.Element` | - | Horizontal track element |
| renderVerticalTrack | `func: () => JSX.Element` | - | Vertical track element |
| renderHorizontalThumb | `func: () => JSX.Element` | - | Horizontal thumb element |
| renderVerticalThumb | `func: () => JSX.Element` | - | Vertical thumb element |
| hideTracksWhenNotNeed | boolean | false | Hide tracks (`visibility: hidden`) when content does not overflow container. |
| thumbSize | Number | - | Set a fixed size for thumbs in px. |
| thumbMinSize | Number | 30 | Minimal thumb size in px. |
| autoHide | boolean | false | Enable auto-hide mode. When `true` tracks will hide automatically and are only visible while scrolling. |
| autoHideTimeout | Number | 1000 | Hide delay in ms. |
| autoHideDuration | Number | 200 | Duration for hide animation in ms. |
| autoHeight | boolean | false | Enable auto-height mode. When `true` container grows with content |
| autoHeightMin | Number | 0 | Set a minimum height for auto-height mode |
| autoHeightMax | Number | 200 | Set a maximum height for auto-height mode |
| universal | boolean | false | Enable universal rendering. [Learn how to use universal rendering](https://reactjs.org/docs/react-dom-server.html) |
| customScrollbarWidth | number | - | custom scrollbar size |

### Scrollbars Values

| params| type | default | description |
| ------ | ------ | ------ | ------ |
| top | Number | - | scrollTop progess, from 0 to 1 |
| left | Number | - | scrollLeft progess, from 0 to 1 |
| clientWidth | Number | - | Width of the view |
| clientHeight | Number | - | Height of the view |
| scrollWidth, | Number | - | Native scrollWidth |
| scrollHeight  | Number | - | Native scrollHeight |
| scrollLeft  | Number | - | Native scrollLeft |
| scrollTop | Number | - | Native scrollTop |

### Scrollbars Methods

* `scrollTop(top = 0)`: scroll to the top value
* `scrollLeft(left = 0)`: scroll to the left value
* `scrollToTop()`: scroll to top
* `scrollToBottom()`: scroll to bottom
* `scrollToLeft()`: scroll to left
* `scrollToRight()`: scroll to right
* `getScrollLeft()`: get scrollLeft value
* `getScrollTop()`: get scrollTop value
* `getScrollWidth()`: get scrollWidth value
* `getScrollHeight()`: get scrollHeight value
* `getClientWidth()`: get view client width
* `getClientHeight()`: get view client height
* `getValues()`: get an object with values about the current position.

## ScrollArea

### ScrollArea usage

```js
import ScrollArea from 'ray-scrollbar/lib/scrollarea';

class ScrollAreaDemo extends Component {
  render() {
    return (
      <div style={{ width: '200px', height: '200px' }}>
        <ScrollArea>
          <div style={{ height: '900px' }}>content ...</div>
        </ScrollArea>
      </div>
    );
  }
}

export default ScrollAreaDemo;
```

### ScrollArea props

```js
ScrollArea.childContextTypes = {
  scrollArea: PropTypes.object
};

ScrollArea.propTypes = {
  children: PropTypes.node,
  // CSS class names added to main scroll area component.
  className: PropTypes.string,
  // Inline styles applied to the main scroll area component.
  style: PropTypes.object,
  // Scroll speed applied to mouse wheel event. **Default: 1**
  speed: PropTypes.number,
  // CSS class names added to element with scroll area content.
  contentClassName: PropTypes.string,
  // Inline styles applied to element with scroll area content.
  contentStyle: PropTypes.object,
  // When set to false, vertical scrollbar will not be available, regardless of the content height.**Default: true**
  vertical: PropTypes.bool,
  // Inline styles applied to vertical scrollbar's container.
  verticalContainerStyle: PropTypes.object,
  // Inline styles applied to vertical scrollbar.
  verticalScrollbarStyle: PropTypes.object,
  // When set to false, horizontal scrollbar will not be available. **Default: true**
  horizontal: PropTypes.bool,
  // Inline styles applied to horizontal scrollbar's container.
  horizontalContainerStyle: PropTypes.object,
  // Inline styles applied to horizontal scrollbar.
  horizontalScrollbarStyle: PropTypes.object,
  /*
  `onScroll(value: Object)` event which can notify the parent component when the container scrolls.
    - `value: Object` - informations about current position
    - `value.leftPosition: Number` - content left position (distance in pixels from the left side of container)
    - `value.topPosition: Number` - content top position (distance in pixels from the top of container)
    - `value.containerHeight: Number` - container height
    - `value.containerWidth: Number` - container width
    - `value.realHeight: Number` - real content height
    - `value.realWidth: Number` - real content width
  */
  onScroll: PropTypes.func,
  // You can override window to make scrollarea works inside iframe. **Default: window**
  contentWindow: PropTypes.any,
  // You can override document to make scrollarea works inside iframe. **Default: document**
  ownerDocument: PropTypes.any,
  // Using this prop it's possible to set minimal size in px for both scrollbars.
  minScrollSize: PropTypes.number,
  // After set to true, mouse wheel event has swapped directions.
  // So normal scrolling moves horizontal scrollbar and scrolling with SHIFT key moves vertical scrollbar.
  // It could be useful for applications with horizontal layout. **Default: false**
  swapWheelAxes: PropTypes.bool,
  // After set to true, mouse wheel event will not propagate.
  // This option is specifically useful in preventing nested scroll areas from propagating scroll actions to parent scroll areas.
  // **Default: false**
  stopScrollPropagation: PropTypes.bool,
  // After set to a number, scrollarea-content is rendered with a tabindex value set to the passed in.
  // This option is specifically useful in allowing the scroll area to be focusable. **Default: undefined**
  focusabconstabIndex: PropTypes.number,
  // In some scenarios, it is necessary to set the custom scrollbar size and automatically calculate the scrollbar size. In the body zoom scenario, bugs may occur
  customScrollbarWidth: PropTypes.number
};
```

### ScrollArea Context

use context

```js

class Content extends Component {
  ...
}

Content.contextTypes = {
  scrollArea: PropTypes.object
};

// context methods
this.context.scrollArea.refresh(); // That method allows manual refreshing of the scrollbar.
this.context.scrollArea.scrollTop(); // It allows to scroll to the top of `ScrollArea` component.
this.context.scrollArea.scrollBottom(); // It allows to scroll to the bottom of `ScrollArea` component.
// It moves vertical scrollbar. `topPosition` is a distance between the top of `scrollArea` container and the top of `scrollArea` content.
this.context.scrollArea.scrollXTo(topPosition);
this.context.scrollArea.scrollLeft(); // It allows to scroll to the left of `ScrollArea` component.
this.context.scrollArea.scrollRight(); // It allows to scroll to the right of `ScrollArea` component.
// It moves horizontal scrollbar. `leftPosition` is a distance between left edge of `scrollArea` container and left edge of `scrollArea` content.
this.context.scrollArea.scrollYTo(leftPosition);
```

## changelog

### v1.0.4

modify `Scrolbar` autoHide content hover

### v1.0.3

add `ScrollArea`

### v1.0.2

add `horizontalTrackClassName` and `verticalTrackClassName`

## License

MIT

---
_Source: https://npm.io/package/ray-scrollbar · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._