Types of transitions

Types

The types of transitions.

SectionTransitionsDraftDocumented, not reviewed yet: the API can change.

Transition

Type

How a screen comes and goes; the way back is the same in reverse. A preset, a preset with its duration, the zoom of iOS 18 out of the view with a nativeID, or views that move from this screen into the new one (nativeID pairs, with a fade of the rest unless type says otherwise).

type Transition =
  | TransitionPreset
  | { type: TransitionPreset; duration?: number }
  | { zoom: string }
  | { shared: [from: string, to: string][]; type?: TransitionPreset; duration?: number }

Member	Type	Description
typeRequired	TransitionPreset
duration	number
zoomRequired	string
sharedRequired	[from: string, to: string][]

Defined in src/api/commands/transitions.ts ↗

TransitionPreset

Type

A ready transition: how a screen comes, and the same in reverse when it goes.

type TransitionPreset = 'platform' | 'none' | 'fade' | 'slideUp' | 'slideFromEnd' | 'scale'

Defined in src/api/commands/transitions.ts ↗

ScreenAnimationOptions

Interface

One side of the transition of a screen: the screen that comes (enter) or the one that goes (exit). It animates the view of the screen. A property with a from or a to makes the animation the library's own; the side without one stands still. Properties set in a layer above replace the set of the layers below, while enabled and waitForRender merge key by key.

interface ScreenAnimationOptions extends ViewAnimationOptions

Member	Type	Description
enabled	boolean	Whether the side plays. `false` turns the side off, also when its properties come from the default options; on `showModal.enter`, `dismissModal.exit` and `setRoot.enter` it turns off the whole animation of the command. A sheet on Android keeps the Material sheet's own motion: it has no way to show or close at once.
waitForRender	boolean	Whether the transition waits for the screen to be drawn. Read on `setRoot.enter` and `showModal.enter`: without it the transition waits for the first mount for half a second at most, `true` waits as long as it takes, `false` starts at once, also with an animation of its own. Other sides don't read it.
x	OptionsAnimationPropertyConfig	The position of the view in its parent. `{ to: 300 }` moves the view to 300, `{ from: 0 }` brings it from 0 to where it stands.
y	OptionsAnimationPropertyConfig	The position of the view in its parent, vertically; like `x`.
translationX	OptionsAnimationPropertyConfig	The shift of the view from its place, horizontally. A missing end is `0`.
translationY	OptionsAnimationPropertyConfig	The shift of the view from its place, vertically. A missing end is `0`.
alpha	OptionsAnimationPropertyConfig	The opacity of the view, from 0 to 1. A missing end is the opacity the view had before the transition.
scaleX	OptionsAnimationPropertyConfig	The scale of the view horizontally, around its center. A missing end is `1`.
scaleY	OptionsAnimationPropertyConfig	The scale of the view vertically, around its center. A missing end is `1`.
rotationX	OptionsAnimationPropertyConfig	The tilt of the view around the horizontal axis, in degrees, drawn with perspective. A missing end is `0`.
rotationY	OptionsAnimationPropertyConfig	The tilt of the view around the vertical axis, in degrees, drawn with perspective. A missing end is `0`.
rotation	OptionsAnimationPropertyConfig	The turn of the view in the plane of the screen, clockwise, in degrees. A missing end is `0`.

Defined in src/interfaces/options/animations.ts ↗

StackAnimationOptions

Interface

The animations of a command that changes a stack: push, pop (also for popTo and popToRoot) and setStackRoot. Without them, the transition is the platform's own: UIKit's on iOS, the transition between activities on Android.

interface StackAnimationOptions

Member	Type	Description
enabled	boolean	Whether the command is animated; `false` shows or removes the screens at once, at the moment an animated one would have started. On `pop` it is read from the screen that goes.
waitForRender	boolean	Whether to wait for the new top screen to be drawn before the transition. Without it, the transition waits for the first mount of the new top's content, half a second at most, with the platform's transition as with an animation of its own; on a push the options the screen sets as it renders for the first time (`useScreenOptions`, such as its title) are in its bar from the first frame. `true` waits as long as it takes, `false` starts at once, the content drawing as it comes ((Android) a push with `appProvider` still renders the screen first). (iOS) The components of the bar are waited for too, each to its own limit.
content	EnterExitAnimationOptions	The animation of the screens: `enter` for the screen that comes (on a pop, the one that was below), `exit` for the one that goes. A property with a `from` or a `to` makes it an animation of its own, which replaces the platform's transition; the side left out stays still. With one of its own, (Android) the top bar goes with its screen: the bar of the screen that goes leaves with it, and the bar of the screen that comes moves, scales and fades with it; (iOS) UIKit keeps the bar in place and changes its title and buttons at once. (Android) The tab bar doesn't travel with the screens. (Android) When the transition has elements, a push plays only `enter` and a pop only `exit`, and only when that side is a single `alpha`; any other side is not played, and the screen fades in or out in 300 ms around the elements instead. iOS plays the sides as they are set.
topBar	EnterExitAnimationOptions<TopBarAnimationOptions>	The animation of the top bar when it shows or hides because the screens differ in `topBar.visible`. Without it, the bar slides up by its height and back in 300 ms; with a `content` of its own it shows or hides with its screen. iOS animates the bar with UIKit. iOS (not supported)iPadOS (not supported)Android
bottomTabs	EnterExitAnimationOptions<BottomTabsAnimationOptions>	The animation of the tab bar when it shows or hides because the screens differ in their tabs. Without it, the bar travels with the screens in the platform's transition, or slides down by its height and back in 300 ms. iOS animates the bar with UIKit. iOS (not supported)iPadOS (not supported)Android
sharedElementTransitions	SharedElementTransition[]	The views that fly from the screen that goes to the screen that comes. A list that is not empty makes the animation the library's own; `[]` removes the list the layers below give and means no elements. On a pop, set the pairs the other way round.
elementTransitions	ElementTransition[]	The animations of single views of the screens, with or without shared elements. A list that is not empty makes the animation the library's own; `[]` removes the list the layers below give.

Defined in src/interfaces/options/animations.ts ↗

ModalAnimationOptions

Interface

The animation of a modal as it shows (showModal) or is dismissed (dismissModal, dismissAllModals). On show, enter animates the modal and exit the screen under it; on dismiss, exit animates the modal and enter the screen under it. The screen under a modal takes part (iOS) only under a modal that covers the full screen.

A sheet keeps the system's sheet motion on both platforms: (iOS) a modal shown as 'pageSheet', 'formSheet' or without a style, (Android) the Material bottom sheet of 'pageSheet', 'formSheet', 'popover', or of modal.sheet without a style. The sides enter and exit and the lists of elements set here don't apply to it. Without them a modal over the whole screen comes up from the bottom: on iOS by UIKit's modalTransitionStyle, on Android with the system's motion of a window over another, 300 ms up and 250 ms down, without a fade.

(Android) When the modal has elements, enter of a show and exit of a dismiss play only when that side is a single alpha; any other side is not played, and the modal fades in or out in 300 ms around the elements instead.

interface ModalAnimationOptions extends EnterExitAnimationOptions

Member	Type	Description
sharedElementTransitions	SharedElementTransition[]	The views that fly from the screen under the modal to the modal. On dismiss, the pairs run the other way round. `[]` removes the list the layers below give.
elementTransitions	ElementTransition[]	The animations of single views of the screens. `[]` removes the list the layers below give.
zoom	ZoomTransitionOptions	(iOS 18+) The zoom of the modal out of a view of the screen that shows it, and back into it on dismiss. Read on `showModal` only. An animation of the sides or elements takes precedence over it.
enter	Side	The animation of the side that comes: the new screen, the modal, the new root.
exit	Side	The animation of the side that goes: the screen that is covered or left, the modal, the old root.

Defined in src/interfaces/options/animations.ts ↗

EnterExitAnimationOptions

Interface

The animations of the two sides of a transition: enter for what comes, exit for what goes. A side left out stays still; one that is set without the other does not move the other.

interface EnterExitAnimationOptions<Side = ScreenAnimationOptions>

Member	Type	Description
enter	Side	The animation of the side that comes: the new screen, the modal, the new root.
exit	Side	The animation of the side that goes: the screen that is covered or left, the modal, the old root.

Defined in src/interfaces/options/animations.ts ↗

ViewAnimationOptions

Interface

The animated properties of a view. Each one is an OptionsAnimationPropertyConfig. Properties are independent of each other: scaling and rotating happen around the center of the view, and a translation is neither scaled nor rotated with it. The one exception is a position with a translation along the same axis, x with translationX and y with translationY: they move the same thing, so set only one of them on a side. With both, the translation plays and the position doesn't. Distances are in points on iOS and dp on Android.

interface ViewAnimationOptions

Member	Type	Description
x	OptionsAnimationPropertyConfig	The position of the view in its parent. `{ to: 300 }` moves the view to 300, `{ from: 0 }` brings it from 0 to where it stands.
y	OptionsAnimationPropertyConfig	The position of the view in its parent, vertically; like `x`.
translationX	OptionsAnimationPropertyConfig	The shift of the view from its place, horizontally. A missing end is `0`.
translationY	OptionsAnimationPropertyConfig	The shift of the view from its place, vertically. A missing end is `0`.
alpha	OptionsAnimationPropertyConfig	The opacity of the view, from 0 to 1. A missing end is the opacity the view had before the transition.
scaleX	OptionsAnimationPropertyConfig	The scale of the view horizontally, around its center. A missing end is `1`.
scaleY	OptionsAnimationPropertyConfig	The scale of the view vertically, around its center. A missing end is `1`.
rotationX	OptionsAnimationPropertyConfig	The tilt of the view around the horizontal axis, in degrees, drawn with perspective. A missing end is `0`.
rotationY	OptionsAnimationPropertyConfig	The tilt of the view around the vertical axis, in degrees, drawn with perspective. A missing end is `0`.
rotation	OptionsAnimationPropertyConfig	The turn of the view in the plane of the screen, clockwise, in degrees. A missing end is `0`.

Defined in src/interfaces/options/animations.ts ↗

TopBarAnimationOptions

Interface

One side of the animation of the top bar, played when the bar shows or hides during a transition. (Android) iOS moves the bar together with the transition by itself and ignores it. The waitForRender of a bar is not read.

interface TopBarAnimationOptions extends ViewAnimationOptions

Member	Type	Description
enabled	boolean	Whether the bar shows or hides with this side's animation; `false` shows or hides it without animation.
x	OptionsAnimationPropertyConfig	The position of the view in its parent. `{ to: 300 }` moves the view to 300, `{ from: 0 }` brings it from 0 to where it stands.
y	OptionsAnimationPropertyConfig	The position of the view in its parent, vertically; like `x`.
translationX	OptionsAnimationPropertyConfig	The shift of the view from its place, horizontally. A missing end is `0`.
translationY	OptionsAnimationPropertyConfig	The shift of the view from its place, vertically. A missing end is `0`.
alpha	OptionsAnimationPropertyConfig	The opacity of the view, from 0 to 1. A missing end is the opacity the view had before the transition.
scaleX	OptionsAnimationPropertyConfig	The scale of the view horizontally, around its center. A missing end is `1`.
scaleY	OptionsAnimationPropertyConfig	The scale of the view vertically, around its center. A missing end is `1`.
rotationX	OptionsAnimationPropertyConfig	The tilt of the view around the horizontal axis, in degrees, drawn with perspective. A missing end is `0`.
rotationY	OptionsAnimationPropertyConfig	The tilt of the view around the vertical axis, in degrees, drawn with perspective. A missing end is `0`.
rotation	OptionsAnimationPropertyConfig	The turn of the view in the plane of the screen, clockwise, in degrees. A missing end is `0`.

Defined in src/interfaces/options/animations.ts ↗

OptionsAnimationPropertyConfig

Interface

The animation of one property of a view: its start, its end, how long it takes and with which curve. A number that is not finite is ignored, a duration or startDelay below 0 or not a number counts as not set. A property with neither from nor to does not animate. While startDelay runs the property holds its start value; when it is done it holds its end value while other properties still run.

interface OptionsAnimationPropertyConfig

Member	Type	Description
from	number	The value the property starts from. Without it, the view's own value: for `x` and `y` where the view stands, for `alpha` what it was before the transition, for a translation `0`, for a scale `1`, for a rotation `0`.
to	number	The value the property ends at. Without it, the view's own value, as for `from`. The last frame sets it exactly.
duration	number	The time the property takes, in milliseconds. The transition lasts until the latest `startDelay` plus `duration` of everything that animates.
startDelay	number	The time to wait before the property starts, in milliseconds. It counts into the length of the transition.
interpolation	Interpolation	The curve of the property. Without it, the property moves linearly.

Defined in src/interfaces/options/animations.ts ↗

Interpolation

Type

How a value gets from its start to its end over the time of a property: a curve type and the parameters that curve takes. Both platforms draw the same curves. Without it, or with an unknown type, the value moves linearly. The last frame always sets the end value exactly, whatever the curve does on the way.

type Interpolation =
  | {
      /** Constant speed. */
      type: 'linear';
    }
  | {
      /** Starts slowly and speeds up. */
      type: 'accelerate';
      /**
       * The strength of the curve: the progress is the time raised to the power of twice this number, so `1` gives the
       * square and a larger number starts slower.
       * @default 1
       */
      factor?: number;
    }
  | {
      /** Starts fast and slows down towards the end. */
      type: 'decelerate';
      /**
       * The strength of the curve: the way left is raised to the power of twice this number, so `1` gives the
       * mirror of the square and a larger number ends slower.
       * @default 1
       */
      factor?: number;
    }
  | {
      /** Slow at both ends and fast in the middle. */
      type: 'accelerateDecelerate';
    }
  | {
      /** Fast at both ends and slow in the middle. */
      type: 'decelerateAccelerate';
    }
  | {
      /** The standard curve of Material motion: a quick start and a long, soft landing. */
      type: 'fastOutSlowIn';
    }
  | {
      /** Runs past the end value and comes back to it. */
      type: 'overshoot';
      /**
       * How far the value runs past its end; `0` does not overshoot.
       * @default 1
       */
      tension?: number;
    }
  | {
      /**
       * A mass on a spring with damping, played in real time: the `duration` of the property is the time the spring
       * has to settle, and a spring that is not settled by then jumps to the end value on the last frame. With the
       * default values the spring needs about 0.8 s, so a short duration cuts it off. A `mass`, `damping` or `stiffness`
       * of 0 or less counts as its default.
       */
      type: 'spring';
      /**
       * The mass.
       * @default 3
       */
      mass?: number;
      /**
       * The damping of the spring.
       * @default 500
       */
      damping?: number;
      /**
       * The stiffness of the spring.
       * @default 200
       */
      stiffness?: number;
      /**
       * Whether a spring damped more than critically is allowed to creep. Without it, such a spring is treated as
       * critically damped and reaches the end as fast as it can without swinging.
       * @default false
       */
      allowsOverdamping?: boolean;
      /**
       * The speed the spring starts with, as a share of the way per second.
       * @default 0
       */
      initialVelocity?: number;
    }

Member	Type	Description
typeRequired	'linear'	Constant speed.
factor	number	The strength of the curve: the progress is the time raised to the power of twice this number, so `1` gives the square and a larger number starts slower.
tension	number	How far the value runs past its end; `0` does not overshoot.
mass	number	The mass.
damping	number	The damping of the spring.
stiffness	number	The stiffness of the spring.
allowsOverdamping	boolean	Whether a spring damped more than critically is allowed to creep. Without it, such a spring is treated as critically damped and reaches the end as fast as it can without swinging.
initialVelocity	number	The speed the spring starts with, as a share of the way per second.

Defined in src/interfaces/options/animations.ts ↗

ElementTransition

Interface

An animation of one view of a screen that moves together with the transition, with or without a counterpart on the other screen. The view is found by its nativeID, first on the screen that goes, then on the one that comes; one that is not found is skipped while the rest plays. The transition waits until it is found. An element that fails on the way (an error in its animation) is skipped too, with a warning in the log: it shows and hides with its screen, and the transition and its command go on. Without an animation of the screens of its own, the screen that comes fades in (or the one that goes fades out) in 300 ms around the elements. When the transition ends or is cancelled, the element gets its own values back. The element's own transform counts: a property that doesn't animate keeps the element's value, and a missing end is that value (a turn read from −180° to 180°, as React Native draws it). x and y are the position in the parent of the element on both platforms. As on a side of a screen, don't set x with translationX or y with translationY on one element: the translation plays and the position doesn't. The element plays where it is, in its screen: it moves with its screen, its parents clip it, and the views drawn after it in its screen stay over it.

interface ElementTransition

Member	Type	Description
idRequired	string	The `nativeID` of the view to animate.
alpha	ElementAnimation	The opacity of the element.
x	ElementAnimation	The position of the element in its parent; a missing end is where the element stands.
y	ElementAnimation	The position of the element in its parent, vertically; like `x`.
translationX	ElementAnimation	The shift of the element from its place, horizontally.
translationY	ElementAnimation	The shift of the element from its place, vertically.
scaleX	ElementAnimation	The scale of the element horizontally, around its center.
scaleY	ElementAnimation	The scale of the element vertically, around its center.
rotationX	ElementAnimation	The tilt of the element around the horizontal axis, in degrees, drawn with perspective.
rotationY	ElementAnimation	The tilt of the element around the vertical axis, in degrees, drawn with perspective.
rotation	ElementAnimation	The turn of the element in the plane of the screen, clockwise, in degrees.

Defined in src/interfaces/options/animations.ts ↗

ElementAnimation

Type

The animation of one property of an element: appearing (with a from) or disappearing (with a to). Giving both ends is allowed. A property with neither does not animate.

type ElementAnimation = AppearingElementAnimation | DisappearingElementAnimation

Member	Type	Description
fromRequired	number	The start value. The element holds it while `startDelay` runs.
to	number	The end value. Leave it out to end at the element's own value.
durationRequired	number	The time the property takes, in milliseconds.
startDelay	number	The time to wait before the property starts, in milliseconds.
interpolation	Interpolation	The curve of the property. Without it, the property moves linearly.

Defined in src/interfaces/options/animations.ts ↗

AppearingElementAnimation

Interface

The animation of a property of an element that comes into its place. It starts from from and ends at the value the element has on its screen. duration is required; without a startDelay it starts at once.

interface AppearingElementAnimation

Member	Type	Description
fromRequired	number	The start value. The element holds it while `startDelay` runs.
to	number	The end value. Leave it out to end at the element's own value.
durationRequired	number	The time the property takes, in milliseconds.
startDelay	number	The time to wait before the property starts, in milliseconds.
interpolation	Interpolation	The curve of the property. Without it, the property moves linearly.

Defined in src/interfaces/options/animations.ts ↗

DisappearingElementAnimation

Interface

The animation of a property of an element that leaves. It starts from the value the element has on its screen and ends at to. When the transition ends or is cancelled, the element gets its own value back, so an element that left with alpha: { to: 0 } is visible again when its screen comes back. duration is required.

interface DisappearingElementAnimation

Member	Type	Description
from	number	The start value. Leave it out to start from the element's own value.
toRequired	number	The end value.
durationRequired	number	The time the property takes, in milliseconds.
startDelay	number	The time to wait before the property starts, in milliseconds. The element holds its start value meanwhile.
interpolation	Interpolation	The curve of the property. Without it, the property moves linearly.

Defined in src/interfaces/options/animations.ts ↗

SharedElementTransition

Interface

A view that flies from the screen that goes to the screen that comes, changing its place, size, corners and look on the way. A pair whose view is not found on either screen is skipped while the rest plays, and the transition waits until the views are found. A pair that fails on the way (an error in its start or its flight) is skipped too, with a warning in the log: its views show and hide with their screens, and the transition and its command go on. So is a pair with a view without a size, or one whose picture can't be taken. Without an animation of the screens of its own, the screen that comes fades in (or the one that goes fades out) in 300 ms around the pair. What flies is a copy: pictures of the two views taken as the transition starts, while the views stay hidden in their places; what changes in them meanwhile shows when they are back. A view its parents cut (overflow: hidden, a scroll view, the edge of its screen) shows only the part they leave visible, and that part goes to the one of the other view on the way. Text keeps its proportions, flies whole and changes its picture within a quarter of the flight. A view turned or scaled by its own transform or by a parent's flies from where it shows, and its angle goes to the other view's along the shorter arc. The angle is the one React Native draws, from −180° to 180°: rotate: '270deg' turns back a quarter, and no pair spins a full turn. (Android) An image without a background or a border flies as the image of the view that comes, from the part and place the fit (resizeMode) shows in one view to those in the other, and an animated image plays on; images of other proportions fly as pictures. An image that doesn't load within a second drops out of the transition. A skew and a tilt (skewX, rotateX, …) don't fly: the view flies without them and has them again at the end.

interface SharedElementTransition

Member	Type	Description
fromIdRequired	string	The `nativeID` of the view on the screen that goes.
toIdRequired	string	The `nativeID` of the view on the screen that comes.
duration	number	The time of the flight, in milliseconds. Without it, 300 ms on iOS; on Android the length of the fade of the screen in this transition, 300 ms unless set.
startDelay	number	The time to wait before the flight, in milliseconds.
interpolation	Interpolation	The curve of the whole flight (place, size, corners, look). A spring runs in real time over the `duration`. Without it, the flight is linear.

Defined in src/interfaces/options/animations.ts ↗

ZoomTransitionOptions

Interface

(iOS 18+) The system zoom transition: the new screen or modal grows out of a view of the screen it comes from, and shrinks back into it when it goes, also under the finger of a swipe. An animation of the screens of your own or a list of elements takes precedence over the zoom. Without the view, or before iOS 18, the transition is the usual one. Android doesn't zoom.

interface ZoomTransitionOptions

Member	Type	Description
fromIdRequired	string \| null	The `nativeID` of the view the screen grows out of, looked for on the screen that is shown when the command runs. An empty string or `null` turns the zoom off.
enabled	boolean	Whether the zoom is on. `fromId` alone turns it on; `false` gives the usual transition.

Defined in src/interfaces/options/animations.ts ↗

PreviewAction

Interface

An item of the menu under a preview; with actions, a submenu.

interface PreviewAction

Member	Type	Description
idRequired	string
titleRequired	string
style	'default' \| 'selected' \| 'destructive'
onPress	() => void
actions	PreviewAction[]

Defined in src/api/hooks/usePreview.ts ↗

PreviewConfig

Type

What a view previews: the screen with its props, and the menu under it.

type PreviewConfig<Name extends ScreenName> = {
  screen: Name;
  actions?: PreviewAction[];
  /** The width of the preview; the width of the screen without it. */
  width?: number;
  /** The height of the preview; the height of the screen without it. */
  height?: number;
} & (Partial<ScreenProps<Name>> extends ScreenProps<Name>
  ? { props?: ScreenProps<Name> }
  : { props: ScreenProps<Name> })

Member	Type	Description
screenRequired	Name
actions	PreviewAction[]
width	number	The width of the preview; the width of the screen without it.
height	number	The height of the preview; the height of the screen without it.
props	ScreenProps<Name>

Defined in src/api/hooks/usePreview.ts ↗

PreviewCompletedEvent

Type

type PreviewCompletedEvent = NavigationEvents['previewCompleted']

Member	Type	Description
previewComponentIdRequired	string	The id of the screen of the preview.
screenRequired	ScreenRef

Defined in src/api/events/navigationEvents.ts ↗

Transition​

TransitionPreset​

ScreenAnimationOptions​

StackAnimationOptions​

ModalAnimationOptions​

EnterExitAnimationOptions​

ViewAnimationOptions​

TopBarAnimationOptions​

OptionsAnimationPropertyConfig​

Interpolation​

ElementTransition​

ElementAnimation​

AppearingElementAnimation​

DisappearingElementAnimation​

SharedElementTransition​

ZoomTransitionOptions​

PreviewAction​

PreviewConfig​

PreviewCompletedEvent​

Transition

TransitionPreset

ScreenAnimationOptions

StackAnimationOptions

ModalAnimationOptions

EnterExitAnimationOptions

ViewAnimationOptions

TopBarAnimationOptions

OptionsAnimationPropertyConfig

Interpolation

ElementTransition

ElementAnimation

AppearingElementAnimation

DisappearingElementAnimation

SharedElementTransition

ZoomTransitionOptions

PreviewAction

PreviewConfig

PreviewCompletedEvent