Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/react-navigation/hooks
React hooks for convenient react-navigation use
https://github.com/react-navigation/hooks
Last synced: about 2 months ago
JSON representation
React hooks for convenient react-navigation use
- Host: GitHub
- URL: https://github.com/react-navigation/hooks
- Owner: react-navigation
- License: mit
- Archived: true
- Created: 2018-10-30T07:35:55.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2022-12-03T03:20:30.000Z (about 2 years ago)
- Last Synced: 2024-04-14T08:30:45.342Z (8 months ago)
- Language: TypeScript
- Homepage: https://reactnavigation.org
- Size: 1.16 MB
- Stars: 575
- Watchers: 19
- Forks: 36
- Open Issues: 24
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
- awesome - hooks - React hooks for convenient react-navigation use (TypeScript)
- awesome-list - hooks - navigation use | react-navigation | 559 | (TypeScript)
README
# React Navigation Hooks (v3/v4 only)
[](https://badge.fury.io/js/react-navigation-hooks) [](https://www.npmjs.com/package/react-navigation-hooks) [](https://circleci.com/gh/react-navigation/hooks/tree/master) [](https://reactnavigation.org/docs/contributing.html)
🏄♀️ Surfing the wave of React Hook hype with a few convenience hooks for `@react-navigation/core` v3/v4. Destined to work on web, server, and React Native. Contributions welcome!
## Only for react-navigation v3 / v4 (not v5)
[react-navigation v5](https://reactnavigation.org/blog/2020/02/06/react-navigation-5.0.html) is officially released as stable, and includes similar, but rewritten hooks (it should be easy to upgrade from v4 to v5).
If you use react-navigation v5, you should import hooks from react-navigation v5 directly, and should not add this project.
## Docs
`yarn add react-navigation-hooks`
`import { useNavigation, useNavigationParam, ... } from 'react-navigation-hooks'`
### useNavigation()
This is the main convenience hook. It provides the regular navigation prop, as you'd get via the screen prop or by using `withNavigation`.
You can use the navigate functionality anywhere in your app:
```js
function MyLinkButton() {
// be careful to never call useNavigation in the press callback. Call hooks directly from the render function!
const { navigate } = useNavigation();
return (
{
navigate('Home');
}}
title="Go Home"
/>
);
}
```
### useNavigationParam(paramName)
Access a param for the current navigation state
```js
function MyScreen() {
const name = useNavigationParam('name');
return
name is {name}
;
}
```
Literally the same as `useNavigation().getParam(paramName)`
### useNavigationState()
Access the navigation state of the current route, or if you're in a navigator view, access the navigation state of your sub-tree.
```js
function MyScreen() {
const { routeName } = useNavigationState();
return
My route name is {routeName}
;
}
```
Literally the same as `useNavigation().state`
### useNavigationKey()
Convenient way to access the key of the current route.
Literally the same as `useNavigationState().key`
### useNavigationEvents(handler)
Subscribe to navigation events in the current route context.
```js
function ReportNavigationEvents() {
const [events, setEvents] = useState([]);
useNavigationEvents(evt => {
// latest state on evt.state
// prev state on evt.lastState
// triggering navigation action on evt.action
setEvents(events => [...events, evt]);
});
// evt.type is [will/did][Focus/Blur]
return (
<>
{events.map(evt => (
{evt.type}
))}
>
);
}
```
The event payload will be the same as provided by `addListener`, as documented here: https://reactnavigation.org/docs/en/navigation-prop.html#addlistener-subscribe-to-updates-to-navigation-lifecycle
### useIsFocused()
Convenient way to know if the screen currently has focus.
```js
function MyScreen() {
const isFocused = useIsFocused();
return {isFocused ? 'Focused' : 'Not Focused'};
}
```
### useFocusEffect(callback)
Permit to execute an effect when the screen takes focus, and cleanup the effect when the screen loses focus.
```js
function MyScreen() {
useFocusEffect(useCallback(() => {
console.debug("screen takes focus");
return () => console.debug("screen loses focus");
}, []));
return ...;
}
```
**NOTE**: To avoid the running the effect too often, it's important to wrap the callback in useCallback before passing it to `useFocusEffect` as shown in the example. The effect will re-execute everytime the callback changes if the screen is focused.
`useFocusEffect` can be helpful to refetch some screen data on params changes:
```js
function Profile({ userId }) {
const [user, setUser] = useState(null);
const fetchUser = useCallback(() => {
const request = API.fetchUser(userId).then(
data => setUser(data),
error => alert(error.message)
);
return () => request.abort();
}, [userId]);
useFocusEffect(fetchUser);
return ;
}
```
`useFocusEffect` can be helpful to handle hardware back behavior on currently focused screen:
```js
const useBackHandler = (backHandler: () => boolean) => {
useFocusEffect(() => {
const subscription = BackHandler.addEventListener('hardwareBackPress', backHandler);
return () => subscription.remove();
});
};
```
### useFocusState()
**deprecated**: this hook does not exist in v5, you should rather use `useIsFocused`
Convenient way of subscribing to events and observing focus state of the current screen.
```js
function MyScreen() {
const focusState = useFocusState();
return {focusState.isFocused ? 'Focused' : 'Not Focused'};
}
```
One (always, and only one) of the following values will be true in the focus state:
- isFocused
- isBlurring
- isBlurred
- isFocusing
## Web example
See an example web app which uses react-navigation and hooks on the client and the server:
https://github.com/react-navigation/web-server-example