Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/bmcmahen/react-page-controller
horizontal, swipeable gesture views for react
https://github.com/bmcmahen/react-page-controller
carousel gesture react swipeable tabs
Last synced: about 2 months ago
JSON representation
horizontal, swipeable gesture views for react
- Host: GitHub
- URL: https://github.com/bmcmahen/react-page-controller
- Owner: bmcmahen
- Created: 2019-05-05T06:21:09.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2022-12-09T22:11:25.000Z (almost 2 years ago)
- Last Synced: 2024-07-20T10:08:17.536Z (2 months ago)
- Topics: carousel, gesture, react, swipeable, tabs
- Language: TypeScript
- Homepage: https://codesandbox.io/embed/gesture-pagination-with-tabs-hpcst
- Size: 5.02 MB
- Stars: 41
- Watchers: 2
- Forks: 1
- Open Issues: 27
-
Metadata Files:
- Readme: Readme.md
Awesome Lists containing this project
README
# react-page-controller
[](https://www.npmjs.com/package/react-page-controller)
[](https://twitter.com/intent/follow?screen_name=benmcmahen)
React-page-controller is a react library for providing views that can be swiped left or right. It was originally built for use in [Sancho UI](https://github.com/bmcmahen/sancho) and is inspired by the iOS library of the same name.
## Features
- **Built with [react-gesture-responder](https://github.com/bmcmahen/react-gesture-responder) to enable better control over gesture delegation.** This means that you can embed gesture based controls within this gesture view (or embed multiple gesture views within eachother) and delegate between them.
- **Configurable**. Configure the animation spring, enable mouse support, use child render callbacks, etc.
- **Optional lazy loading**.
## Install
Install `react-page-controller` and its peer dependency `react-gesture-responder` using yarn or npm.
```
yarn add react-page-controller react-gesture-responder
```
## Basic usage
The gesture view should be provided with a collection of children, each representing a panel. By default, each child will be wrapped in an element wiith the recommended props. If you'd rather render the element yourself, provide a render callback for each child instead.
```jsx
import Pager from "react-page-controller";
function TabContent() {
const [index, setIndex] = React.useState(0);
return (
setIndex(i)}>
First panel
Second panel
Third panel
{(props, active, load) => fourth panel}
);
}
```
## API
| Name | Type | Default Value | Description |
| -------------------- | --------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| value\* | number | | The current index to show |
| onRequestChange\* | (value: number) => void; | | A callback for handling index changes |
| lazyLoad | boolean | false | Lazy load pane contents |
| enableMouse | boolean | false | By default mouse gestures are not enabled |
| enableGestures | boolean | true | By default gestures are enabled |
| animationConfig | SpringConfig | { tension: 190, friction: 20, mass: 0.4 } | A react-spring config for animations |
| onTerminationRequest | (state) => boolean; | | Optionally prevent parent views from claiming the pan-responder. Useful for embedded gesture views |
| onMoveShouldSet | (state, e, suggested) => boolean; | | Optionally override the default onMoveShouldSet behaviour. Useful for embedding multiple gesture views. |
| enableScrollLock | boolean | true | Lock all page scrolling when making swiping gestures. This is generally the desired behaviour. |
## Imperative API
You can use the imperative API to manually focus the active panel, which is something you'll likely want to do for accessibility reasons.
```jsx
function TabContent() {
const [index, setIndex] = React.useState(0);
const ref = React.useRef();
function focusCurrentIndex() {
ref.current.focus();
}
return (
setIndex(i)}>
First panel
Second panel
Third panel
);
}
```
## Embedding Views
Each Pager exposes the `react-gesture-responder` `onTerminationRequest` function which allows you to negotiate between gesture views competing for the responder. Typically, you'll want the child view to prevent the parent from claiming the responder.
```jsx
Left parent pane
false}>
child pane
another child
```
The logic can become more sophisticated. In the gif at the top of the readme, our parent claims the responder (and prevents the child from stealing it) when showing the first child pane and moving left. The code will look something like this:
```jsx
const [childIndex, setChildIndex] = React.useState(0);
const [parentIndex, setParentIndex] = React.useState(0);
function onMoveShouldSet(state, e, suggested) {
if (suggested) {
if (parentIndex === 0 || (state.delta[0] > 0 && childIndex === 0)) {
return true;
}
}
return false;
}
function onTerminationRequest(state) {
if (state.delta[0] > 0 && childIndex === 0) {
return false;
}
return true;
}
setParentIndex(i)}
>
Left parent pane
setChildIndex(i)}>
child pane
another child
;
```