Cross-platform gesture library for desktop and mobile.
npm install @composi/gesturesCross-platform gesture library for desktop and mobile. Gzipped, @composi/gestures is only 1KB. It's smaller than most images you will use in your app.
To install @composi/gestures, use NPM:
``
npm i -D @composi/gestures
After that you can import it into your project. Do so on the document that will be the main part loading in the browser. @composi/gestures needs to run after the DOM is loaded.
`javascript`
import { gestures } from '@composi/gestures'
// Initialize the gestures:
gestures()
// App code here...
If you fail to execute gestures() after importing, the gestures will never get set up and will be unavailable to your code.
@composi/gestures provides normalised events and custom gestures for desktop and mobile. To facility easier cross-platform event handle, @composi/gestures provides the following four event aliases:
1. eventstart
2. eventend
3. eventmove
4. eventcancel
On desktop these resolve to mousedown, mouseup (click), mousemove and mouseout. On a device with support for pointer events, these become: pointerdown, pointerup, pointermove and pointercancel. On a device that supports touch events these become: touchstart, touchend, touchmove and touchcancel. You can use these event aliases just like you would any other events, with the assurance that they will work the same everywhere:
`javascript
import { eventstart, eventend, eventmove, eventcancel } from '@composi/gestures'
document.querySelector('button').addEventListener(eventend, (e) => {
e.target.classList.toggle('selected')
})
`
On mobile devices users expect to be able to tap and swipe. @composi/gestures provides taps and swipes that work on both mobile and desktop, ensuring an consitent user experience across platforms. With @composi/gestures you don't have to have separate events for desktop and mobile.
@composi/gestures provides the following gestures:
1. tap
2. longtap
3. dbltap
4. swipe
5. swipeleft
6. swiperight
7. swipeup
8. swipedown
There are two ways you can use gestures, as inline events or as event listeners.
Depending on the library/framework you are using, you can use "on" gestures camel cased or lowercase:
`javascript
import { gestures } from '@composi/gestures'
// Initialize the gestures:
gestures()
// Define event callbacks:
function announceTap() {
alert('You just tapped!')
}
function announceSwipe() {
alert('You just swiped!')
}
// Define inline events:
function TappableButton(props) {
return (
)
},
function SwipableButton(props) {
return (
)
}
`
You can also use gestures with event listeners:
`javascript
import { gestures } from '@composi/gestures'
// Initialize the gestures:
gestures()
const tappableBtn = document.querySelector('#tappableBtn')
tappableBtn.addEventListener('tap', function() {
alert('You just tapped the button!')
})
`
swipe is a more generic gesture than swipeleft, etc. However, if you use it, you can examine the event data to see which direction the swipe was:
`javascript
import { gestures } from '@composi/gestures'
// Initialize the gestures:
gestures()
function SwipeTest() {
function announceSwipe(e) {
// The swipe direction gets passed with the event
// as the value of the property data:The swipe direction was: ${e.data}.
alert()`
}
return (
announceSwipe(e)}>Swipe on me!
)
}
By capturing and checking the event data, you can have a single swipe event handle different directions. You might do that with a toggle switch. Attach a swipe gesture to it, and when the event data is left, turn it on, else turn it off.
If you register a swipe on an element and it or its children have any text, when the user tried to swipe it will result in a text selection. You can avoid this glitch by using @composi/gestures's disableTextSelection function. You import it in and the pass it the element to disable text selection on. Below we show how to do this with React. We disable text selection on the button when the componentDidMount lifecycle hook executes:
`javascript
import { React } from 'react'
import { gestures, disableTextSelection } from '@composi/gestures'
// Initialize gestures:
gestures()
class Button extends React.Component {
constructor(props) {
super(props)
this.button = React.createRef();
}
render() {
return (
)
}
handleSwipe(e) {
// Handle the swipe here...
}
componentDidMount() {
// Disable text selection on the button:
disableTextSelection(this.button.current)
}
}
`
If you wish to disable text selection on may element, say all button tags or all elements of a class, you can use the selector followed by a second truthy value:
`javascript`
disableTextSelection('button', true)
// or (any string is truthy)
disableTextSelection('.swipable', 'all')
#### Re-enabling Text Selection
If you want to later re-enable text selection on an element that you disabled, you can import and use the enableTextSelection function. Import it and pass it the element to enable:
`javascript`
enableTextSelection('#user-list')
To re-enable many elements of the same type, you use it the same as disableTextSelection by passing in a tag selector or class, followed by a second truth value:
`javascript`
enableTextSelection('button', true)
// or (any string is truthy)
enableTextSelection('.swipable', 'yes')
@composi/gestures should work with any library or framework that does not convert inline events into synthetic events. Be aware that some libaries expect inline events to be camel cased. @composi/gestures has been tested with Preact, Hyperapp, Superfine, VueJS, Composi, HyperHTML, lit-html, Svelte
`javascript`
class List extends Component {
render() {
return (
)
}
announce(e) {
alert('You just tapped the button!')
}
}
`javascript
const actions = {
announceTap: () => alert('You just tapped the button!')
}
const view = (state, actions) => (
app(null, actions, view, document.body)
`
HTML:
`html`
JavaScript:javascriptYou swiped in this direction: ${e.data}
new Vue({
el: '#app',
methods: {
announceSwipe: function(e) {
alert()`
}
}
})
html
`$3
javascript
let renderGesture = (name) => hyper()
;function handleClick(e) {
e.preventDefault();
alert('You just tapped the button.');
}
hyper(document.body)
${renderGesture()};
`$3
javascript
function announceTap() {
alert('You just tapped the button!')
}render(html
, document.body);
`$3
javascript
function GestureTest() {
function announceDblTap() {
alert('You just double tapped the button!')
}
return (
)
}
`$3
javascript
function List() { announceLongTap(e) {
alert('You just long tapped the button!')
}
return (
)
}
`$3
Because Inferno and React use synthetic events, you can't use @composi/gestures for inline events. However, you can use @composi/gestures with event listeners for them. You'd need to use a
for the element where you want to listen for the gesture. Below is an example with Inferno. Notice how we use ref to get a reference to the button and then use componentDidMount to attach an event listener for the gesture (tap).`javascript
class GestureTest extends Component {
render() {
return (
);
}
componentDidMount(el) {
this.tapBtn.addEventListener('tap', this.announce)
}
announce() {
alert('You just tapped!')
}
}
`And here's a gesture for React:
javascript
import { React } from 'react'
import { ReactDOM } from 'react-dom'
import { gestures } from '@composi/gestures'// Initialize gestures:
gestures()
class Button extends React.Component {
constructor(props) {
super(props)
this.button = React.createRef();
}
render() {
return (
)
}
componentDidMount() {
// Use ref defined on button to attach event listener for tag gesture:
this.button.current.addEventListener('tap', () => this.announce())
}
announce() {
alert('You just tapped!')
}
}ReactDOM.render(
,
document.body
)
``