react-native-listener
v1.1.0
Published
A utility component to allow easy access to browser native events
Downloads
51,380
Maintainers
Readme
react-native-listener
A utility component to allow easy access to browser native events.
THIS IS UNRELATED TO react-native!
Please don't confuse this library with anything to do with React Native. This library is for dealing directly with browser native events.
Why?
React's uses event delegation
with a single event listener on document
. While this is great if your entire application is inside React,
it's not so great if your React component is inserted into a page containing other event listeners. If an
event happens inside your React component, your component will be the last to hear of the event. The
event will first propagate to all its ancestor elements on the page.
Here is a Codesandbox to demonstrate.
If your problem is that you need to stop events leaking out of your React component to the rest of the page,
<NativeListener>
is the solution.
Installation
In your project dir:
npm install --save react-native-listener
Usage
In your JSX file, simply wrap the element (only one!) you want to listen to with <NativeListener>
and
put your event listener properties (e.g. onClick
, onKeyDown
) on <NativeListener>
instead of on your element.
So, instead of this...
import React, {Component} from 'react';
export default class MyComponent extends Component {
handleButtonClick(event) {
// do something (event is React's SyntheticEvent)
}
render() {
return (
<div>
<button onClick={this.handleButtonClick.bind(this)}>Click Me!</button>
</div>
);
}
}
...do this:
import React, {Component} from 'react';
import NativeListener from 'react-native-listener';
export default class MyComponent extends Component {
handleButtonClick(event) {
// do something (event is native browser event)
}
render() {
return (
<div>
<NativeListener onClick={this.handleButtonClick.bind(this)}>
<button>Click Me!</button>
</NativeListener>
</div>
);
}
}
IMPORTANT: The event passed to your function is the native browser event, NOT React's SyntheticEvent!!
Convenience Properties
If all you want to do is stop the propagation of an event, there are convenience properties to do that.
stopClick
, stopKeyDown
. For example, say you wanted to allow normal hyperlinks to work, but your
component is inside some element that JQuery is calling event.preventDefault()
for clicks...
import React, {Component} from 'react';
import NativeListener from 'react-native-listener';
export default class MyComponent extends Component {
render() {
return (
<div>
<NativeListener stopClick>
<a href="https://github.com/erikras/react-native-listener">Check out this awesome code!</a>
</NativeListener>
</div>
);
}
});
IMPORTANT: You cannot just put a <NativeListener stopClick>
surrounding your whole component and
expect regular React events to work inside it. That will also prevent the clicks from bubbling up to
React's event system listening on the document. If you block an event, you must use <NativeListener>
to listen to that event everywhere inside the <NativeListener>
element that is blocking the event.
Note on 1.0.2 Update
If you use react-native-listener >= 1.0.2 in CommonJS environment, don’t forget to add .default
to your import:
- var NativeListener = require('react-native-listener')
+ var NativeListener = require('react-native-listener').default
Advanced Usage
By default, the onClick
, onKeyDown
event listeners fire on bubble. If you understand the
difference between bubble and capture and
you really need to listen on capture, you can simply append Capture
to your event property.
e.g. onClickCapture
, onKeyDownCapture
.
Module written by Erik Rasmussen @erikras