Skip to main content
Version: 3.x

Transitioner

Transitioner is a React component that helps manage transitions for complex animated components. It manages the timing of animations and keeps track of various screens as they enter and leave, but it doesn't know what anything looks like, because rendering is entirely deferred to the developer.

Under the covers, Transitioner is used to implement CardStack, and hence the stack navigator.

The most useful thing Transitioner does is to take in a prop of the current navigation state. When routes are removed from that navigation state, Transitioner will coordinate the transition away from those routes, keeping them on screen even though they are gone from the navigation state.

Example​

class MyNavView extends Component {
  ...
  render() {
    return (
      <Transitioner
        configureTransition={this._configureTransition}
        navigation={this.props.navigation}
        render={this._render}
        onTransitionStart={this.onTransitionStart}
        onTransitionEnd={this.onTransitionEnd}
      />
    );
}

For a small but complete working example, see the CustomTransitioner example from the NavigationPlayground.

Props​

configureTransition function​

Invoked on Transitioner.componentWillReceiveProps, this function allows customization of animation parameters such as duration. The value returned from this function will be fed into a timing function, by default Animated.timing(), as its config.

Examples​

_configureTransition(transitionProps, prevTransitionProps) {
  return {
    // duration in milliseconds, default: 250
    duration: 500,
    // An easing function from `Easing`, default: Easing.inOut(Easing.ease)
    easing: Easing.bounce,
  }
}

Note: duration and easing are only applicable when the timing function is Animated.timing. We can also use a different timing function and its corresponding config parameters, like so:

_configureTransition(transitionProps, prevTransitionProps) {
  return {
    // A timing function, default: Animated.timing.
    timing: Animated.spring,
    // Some parameters relevant to Animated.spring
    friction: 1,
    tension: 0.5,
  }
}

Flow definition​

  configureTransition: (
    transitionProps: NavigationTransitionProps,
    prevTransitionProps: ?NavigationTransitionProps,
  ) => NavigationTransitionSpec,

Parameters​

Returns​

An object with state that represents the navigation state, with routes and an active route index. Also includes dispatch and other methods for requesting actions.

Example value​

{
   // Index refers to the active child route in the routes array.
  index: 1,
  routes: [
    { key: 'DF2FGWGAS-12', routeName: 'ContactHome' },
    { key: 'DF2FGWGAS-13', routeName: 'ContactDetail', params: { personId: 123 } }
  ]
}

Flow definition​

export type NavigationState = {
  index: number,
  routes: Array<NavigationRoute>,
};

For more information about the NavigationRoute type, check out its flow definition.

render function​

Invoked from Transitioner.render(). This function performs the actual rendering delegated from Transitioner. In this function, we can use the information included in the transitionProps and prevTransitionProps parameters to render scenes, create animations and handle gestures.

There are a few important properties of the transitionProps and prevTransitionProps parameters that are useful for the tasks mentioned above:

  • scenes: Array<NavigationScene> - a list of all available scenes
  • position: NavigationAnimatedValue - the progressive index of the transitioner's navigation state
  • progress: NavigationAnimatedValue - the value that represents the progress of the transition when navigation state changes from one to another. Its numeric value will range from 0 to 1.

For the complete list of properties of NavigationTransitionProps, check out its flow definition.

Examples​

transitionProps.scenes is the list of all available scenes. It is up to the implementor to determine how to lay them out on the screen. For example, we can render the scenes as a stack of cards like so:

_render(transitionProps, prevTransitionProps) {
  const scenes = transitionProps.scenes.map(scene => this._renderScene(transitionProps, scene));
  return (
    <View style={styles.stack}>
      {scenes}
    </View>
  );
}

We can then use an Animated.View to animate the transition. To create necessary animated style properties, such as opacity, we can interpolate on position and progress values that come with transitionProps:

_renderScene(transitionProps, scene) {
  const { position } = transitionProps;
  const { index } = scene;
  const opacity = position.interpolate({
    inputRange: [index-1, index, index+1],
    outputRange: [0, 1, 0],
  });
  // The prop `router` is populated when we call `createNavigator`.
  const Scene = this.props.router.getComponent(scene.route.routeName);
  return (
    <Animated.View style={{ opacity }}>
      { Scene }
    </Animated.View>
  )
}

The above code creates a cross fade animation during transition.

For a comprehensive tutorial on how to create custom transitions, see this blog post.

Flow definition​

render: (transitionProps: NavigationTransitionProps, prevTransitionProps: ?NavigationTransitionProps) => React.Node,

Parameters​

Returns​

  • A ReactElement, which will be used to render the Transitioner component

onTransitionStart function​

Invoked when the transition animation is about to start.

If you return a promise from onTransitionStart, the transition animation will begin after the promise is resolved.

Flow definition​

onTransitionStart: (transitionProps: NavigationTransitionProps, prevTransitionProps: ?NavigationTransitionProps) => (Promise | void),

Parameters​

Returns​

  • Promise to delay the start of the transition animation, or none to begin the transition animation immediately.

onTransitionEnd function​

Invoked once the transition animation completes.

If you return a promise from onTransitionEnd, any queued transition animations will begin after the promise is resolved.

Flow definition​

onTransitionEnd: () => void

Parameters​

  • none.

Returns​

  • none.