https://github.com/JedWatson/react-tappable
Tappable component for React
https://github.com/JedWatson/react-tappable
Last synced: 27 days ago
JSON representation
Tappable component for React
- Host: GitHub
- URL: https://github.com/JedWatson/react-tappable
- Owner: JedWatson
- License: mit
- Created: 2014-10-15T06:17:20.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2019-11-16T08:09:57.000Z (over 5 years ago)
- Last Synced: 2025-03-08T08:59:29.996Z (about 1 month ago)
- Language: JavaScript
- Homepage: http://jedwatson.github.io/react-tappable/
- Size: 2.27 MB
- Stars: 862
- Watchers: 26
- Forks: 90
- Open Issues: 20
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGES.md
- License: LICENSE
Awesome Lists containing this project
- awesome-react-components-all - react-tappable - Tappable component for React. (Uncategorized / Uncategorized)
- awesome-list - react-tappable - Tappable component for React. (UI Utilites / Device Input)
README
React-Tappable
==============
Tappable component for React. Abstracts touch events to implement `onTap`, `onPress`, and pinch events.
The events mimic their native equivalents as closely as possible:
* the baseClass (default: `Tappable`) has `-active` or `-inactive` added to it to enable pressed-state styling
* the pressed state is visually cancelled if the touch moves too far away from the element, but resumes if the touch comes back again
* when you start scrolling a parent element, the touch event is cancelled
* if the `onPress` property is set, it will cancel the touch event after the press happens
When touch events are not supported, it will fall back to mouse events. Keyboard events are also supported, emulating the behaviour of native button controls.
## Demo & Examples
Live demo: [jedwatson.github.io/react-tappable](http://jedwatson.github.io/react-tappable/)
To build the examples locally, run:
```
npm install
gulp dev
```
Then open [`localhost:8000`](http://localhost:8000) in a browser.
## Installation
The easiest way to use React-tappable is to install it from npm.
```
npm install react-tappable --save
```
Ensure to include it in your own React build process (using [Browserify](http://browserify.org), etc).
You could also use the standalone build by including `dist/react-tappable.js` in your page; but, if you do this, make sure you have already included React, and that it is available globally.
## Usage
React-tappable generates a React component (defaults to ``) and binds touch events to it.
To disable default event handling (e.g. scrolling) set the `preventDefault` prop.
```jsx
import Tappable from 'react-tappable';
Tap me
```
For a lighter component, you can opt-in to just the features you need:
```jsx
import Tappable from 'react-tappable/lib/Tappable';
import Pinchable from 'react-tappable/lib/Pinchable';
import TapAndPinchable from 'react-tappable/lib/TapAndPinchable';
I respond to Tap events
I respond to Pinch events
In respond to both!
```
The `TapAndPinchable` component is the default one you get when you just import `react-tappable`.
### Properties
* `activeDelay` ms delay before the `-active` class is added, defaults to `0`
* `component` component to render, defaults to `'span'`
* `classes` optional object containing `active` and `inactive` class names to apply to the component; useful with [css-modules](https://github.com/css-modules/css-modules)
* `classBase` base to use for the active/inactive classes
* `className` optional class name for the component
* `moveThreshold` px to allow movement before cancelling a tap; defaults to `100`
* `pressDelay` ms delay before a press event is detected, defaults to `1000`
* `pressMoveThreshold` px to allow movement before ignoring long presses; defaults to `5`
* `preventDefault` (boolean) automatically call preventDefault on all events
* `stopPropagation` (boolean) automatically call stopPropagation on all events
* `style` (object) styles to apply to the component
### Special Events
These are the special events implemented by `Tappable`.
* `onTap` fired when touchStart or mouseDown is followed by touchEnd or mouseUp within the moveThreshold
* `onPress` fired when a touch is held for the specified ms
* `onPinchStart` fired when two fingers land on the screen
* `onPinchMove` fired on any movement while two fingers are on screen
* `onPinchEnd` fired when less than two fingers are left on the screen, onTouchStart is triggerred, if one touch remains
#### Pinch Events
Pinch events come with a special object with additional data to actually be more useful than the native events:
* `touches`: Array of Objects - {identifier, pageX, pageY} - raw data from the event
* `center`: Object - {x, y} - Calculated center between the two touch points
* `angle`: Degrees - angle of the line connecting the two touch points to the X-axis
* `distance`: Number of pixels - beween the two touch points
* `displacement`: Object {x, y} - offset of the center since the pinch began
* `displacementVelocity`: Object {x, y} : Pixels/ms - Immediate velocity of the displacement
* `rotation`: degrees - delta rotation since the beginning of the gesture
* `rotationVelocity`: degrees/millisecond - immediate rotational velocity
* `zoom`: Number - Zoom factor - ratio between distance between the two touch points now over initial
* `zoomVelocity`: zoomFactor/millisecond - immediate velocity of zooming
* `time`: milliseconds since epoch - Timestamp
#### Known Issues
* The pinch implementation has not been thoroughly tested
* Any touch event with 3 three or more touches is completely ignored.
### Native Events
The following native event handlers can also be specified.
* `onKeyDown`
* `onKeyUp`
* `onTouchStart`
* `onTouchMove`
* `onTouchEnd`
* `onMouseDown`
* `onMouseUp`
* `onMouseMove`
* `onMouseOut`
Returning `false` from `onKeyDown`, `onMouseDown`, or `onTouchStart` handlers will prevent `Tappable` from handling the event.
## Changelog
See [CHANGES.md](https://github.com/JedWatson/react-tappable/blob/master/CHANGES.md)
## License
Copyright (c) 2017 Jed Watson. [MIT](LICENSE)