Skip to content

Commit a61e0a6

Browse files
IjzerenHeinIjzerenHein
committed
docs: improved docs & work in progress explanation
1 parent aafdff6 commit a61e0a6

File tree

1 file changed

+122
-11
lines changed

1 file changed

+122
-11
lines changed

‎README.md‎

Lines changed: 122 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,46 @@
1-
# React Navigation Shared Element
1+
# React Navigation Shared Element <!-- omit in toc -->
22

3-
Experimental [react-native-shared-element](https://github.com/IjzerenHein/react-native-shared-element) bindings for React Navigation
3+
Experimental [react-native-shared-element](https://github.com/IjzerenHein/react-native-shared-element) bindings for React Navigation 💫
44

5-
# Work in progress, docs may not be up to date
5+
This library is under development and is subject to API changes. At the moment only the stack navigator is supported.
6+
As [react-navigation](https://reactnavigation.org) is alo undergoing development and possible API changes, this library provides a testing ground and working API for the v3 branch of react-navigation.
7+
It was written as a separate library which does not require any changes to react-navigation itself.
8+
As time progresses, the goal is to support the latest react-navigation version, a cleaner API, support `appear` and `disappear` transitions, and have the
9+
[native extensions](https://github.com/IjzerenHein/react-native-shared-element) land in [Expo](https://expo.io/).
10+
11+
## Index <!-- omit in toc -->
12+
13+
- [Installation](#installation)
14+
- [Usage](#usage)
15+
- [Documentation](#documentation)
16+
- [createSharedElementStackNavigator](#createsharedelementstacknavigator)
17+
- [SharedElement](#sharedelement)
18+
- [Trigger shared element transitions](#trigger-shared-element-transitions)
19+
- [License](#license)
620

721
## Installation
822

923
Open a Terminal in your project's folder and run,
1024

1125
```sh
12-
yarn add react-navigation-sharedelement
26+
yarn add react-navigation-sharedelement react-native-shared-element
1327
```
1428

15-
Make sure to also link the native [react-native-shared-element](https://github.com/IjzerenHein/react-native-shared-element) code.
29+
Make sure to also link [react-native-shared-element](https://github.com/IjzerenHein/react-native-shared-element) into your project.
1630

1731
## Usage
1832

33+
In order to enable shared element transitions, the following steps need to be performed
34+
35+
- Wrap stack-navigator with `createSharedElementStackNavigator`
36+
- Wrap your component with `<SharedElement>` and provide a unique `id`
37+
- When pushing a route, provide a `sharedElements` config
38+
1939
```jsx
2040
import { createStackNavigator } from 'react-navigation';
21-
import { createSharedElementTransitioner } from 'react-navigation-sharedelement';
41+
import { createSharedElementStackNavigator } from 'react-navigation-sharedelement';
2242

23-
const stackNavigator = createSharedElementTransitioner(
43+
const stackNavigator = createSharedElementStackNavigator(
2444
createStackNavigator,
2545
{
2646
List: ListScreen,
@@ -53,7 +73,7 @@ class ListScreen extends React.Component {
5373
const { navigation } = this.props;
5474
navigation.push('Detail', {
5575
sharedElements: [
56-
`itemPhoto.${item.id}`
76+
`item.${item.id}.photo`
5777
]
5878
});
5979
}
@@ -66,14 +86,105 @@ class DetailScreen extends React.Component {
6686
render() {
6787
const item = this.props.navigation.getParam('item');
6888
return (
69-
<SharedElement id={`itemPhoto.${item.id}`}>
89+
<SharedElement id={`item.${item.id}.photo`}>
7090
<Image source={...} />
7191
</SharedElement>
7292
);
7393
}
7494
}
7595
```
7696

77-
## Docs
97+
## Documentation
98+
99+
### createSharedElementStackNavigator
100+
101+
The `createSharedElementStackNavigator` function wraps an existing stack-navigator and makes shared element transitions possible on it.
102+
103+
It performs the following actions
104+
105+
- Creates a top-level renderer to host the shared element transitions
106+
- Wraps each route with a shared element scene
107+
- Detects route changes and trigger shared element transitions
108+
109+
**Arguments**
110+
111+
| Argument | Type | Description |
112+
| ---------------------- | ---------- | ------------------------------------ |
113+
| `createStackNavigator` | `function` | The stack-navigator function to wrap |
114+
| `routeConfig` | `object` | Routes-config |
115+
| `stackNavigatorConfig` | `object` | Stack navigator config |
116+
117+
### SharedElement
118+
119+
The `<SharedElement>` component accepts a single child and a "shared" id. The child is the element that is then available for doing shared element transitions with.
120+
The `id` is the unique screen id by which the element an be identified.
121+
122+
This component is synonymous for the `<SharedElement>` component as defined in `react-native-shared-element`. Instead of a `node` it uses an `id` to create a higher
123+
lever API which automatically ties in with the scenes created by `createSharedElementTransitioner`.
124+
125+
**Props**
126+
127+
| Property | Type | Description |
128+
| --------------- | --------- | ------------------------------------------------------------------------------------ |
129+
| `children` | `element` | A single child component, which must map to a real view in the native view hierarchy |
130+
| `id` | `string` | Unique id of the shared element |
131+
| `View props...` | | Other props supported by View |
132+
133+
### Trigger shared element transitions
134+
135+
In order to trigger a shared element transition, a `sharedElements` config needs to be provided to `navigate` or `push`.
136+
137+
**Example**
138+
139+
```js
140+
navigation.push({
141+
item,
142+
sharedElements: [
143+
`item.${item.id}.photo`,
144+
{id: `item.${item.id}.name`, animation: 'fade'}
145+
]
146+
})
147+
```
148+
149+
> The order of the shared-elements is important as it defines in which order the transitions are rendered onto the screen.
150+
151+
**Full example**
152+
153+
```js
154+
navigation.push({
155+
item,
156+
sharedElements: [
157+
`item.${item.id}.photo`, // <-- is synonymous for:
158+
// {
159+
// id: `item.${item.id}.photo`
160+
// sourceId: `item.${item.id}.photo`,
161+
// animation: 'move',
162+
// resize: 'auto',
163+
// align: 'auto'
164+
// }
165+
{id: `item.${item.id}.name`, animation: 'fade'} // <-- is synonymous for:
166+
// {
167+
// id: `item.${item.id}.name`
168+
// sourceId: `item.${item.id}.name`,
169+
// animation: 'fade',
170+
// resize: 'auto',
171+
// align: 'auto'
172+
// }
173+
]
174+
})
175+
```
176+
177+
The following fields can be defined for each shared-element config
178+
179+
| Field | Type | Description |
180+
| ----------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
181+
| `id` | `string` | Id that corresponds to the `id` specified in the `<SharedElement>` component |
182+
| `sourceId` | `string` | Alternative id to use for the source element. This field an be used to create transitions between elements with different `id`s |
183+
| `animation` | `move | fade` | Type of animation to perform (default = `move`), [see SharedElementAnimation](https://github.com/IjzerenHein/react-native-shared-element#sharedelementanimation) |
184+
| `resize` | `auto | stretch | clip | none` | Resize behavior of the transition (default = `auto`), [see SharedElementResize](https://github.com/IjzerenHein/react-native-shared-element#sharedelementresize) |
185+
| `align` | `auto | top-left | ...` | Align behavior of the transition (default = `auto`), [see SharedElementAlign](https://github.com/IjzerenHein/react-native-shared-element#sharedelementalign) | |
186+
187+
188+
## License
78189

79-
TODO
190+
React navigation shared element library is licensed under [The MIT License](./LICENSE.md).

0 commit comments

Comments
 (0)