Join us for ⁠#Android11: The Beta Launch Show on June 3!

TransitionDefinition

class TransitionDefinition<T>
kotlin.Any
   ↳ androidx.animation.TransitionDefinition

TransitionDefinition contains all the animation related configurations that will be used in a state-based transition. It holds a set of TransitionStates and an optional set of TransitionSpecs. It can be used in android.ui.animation.Transition to create a state-based animation in Compose.

Each TransitionState specifies how the UI should look in terms of values associated with properties that differentiates the UI from one conceptual state to anther. Each TransitionState can be considered as a snapshot of the UI in the form of property values.

TransitionSpec defines how to animate from one state to another with a specific animation for each property defined in the states. TransitionSpec can be created using transition method inside of a TransitionDefinition. Currently the animations supported in a transition are: TransitionSpec.tween, TransitionSpec.keyframes, TransitionSpec.physics, TransitionSpec.snap, TransitionSpec.repeatable. When no TransitionSpec is specified, the default TransitionSpec.physics animation will be used for all properties involved. Similarly, when no animation is provided in a TransitionSpec for a particular property, the default physics animation will be used. For each transition, both the from and the to state can be omitted. Omitting in this case is equivalent to a wildcard on the starting state or ending state. When both are omitted at the same time, it means this transition applies to all the state transitions unless a more specific transition have been defined.

To create a TransitionDefinition, there are generally 3 steps involved:

Step 1: Create PropKeys. One PropKey is required for each property/value that needs to be animated. These should be file level properties, so they are visible to TransitionDefinition ( which will be created in step 3).

    val radius = FloatPropKey()
    val alpha = FloatPropKey()

Step 2 (optional): Create state names.

This is an optional but recommended step to create a reference for different states that the animation should end at. State names can be of type T, which means they can be string, integer, etc, or any custom object, so long as they are consistent.

It is recommended to either reuse the states that you already defined (e.g. TogglableState.On, TogglableState.Off, etc) for animating those state changes, or create an enum class for all the animation states.

    enum class ButtonState {
        Released, Pressed, Disabled
    }

Step 3: Create a TransitionDefinition using the animation DSL.

TransitionDefinition is conceptually an animation configuration that defines:

  1. States, each of which are described as a set of values. Each value is associated with a PropKey.
  2. Optional transitions, for how to animate from one state to another.
import androidx.animation.transitionDefinition

val definition = transitionDefinition {
    state(ButtonState.Pressed) {
        this[alpha] = 0f
        this[radius] = 200f
    }
    state(ButtonState.Released) {
        this[alpha] = 0f
        this[radius] = 60f
    }

    // Optional configuration for transition from Pressed to Released. If no transition is
    // defined, the default physics-based transition will be used.
    transition(fromState = ButtonState.Released, toState = ButtonState.Pressed) {
        radius using physics {
            dampingRatio = 1.0f
        }
        alpha using keyframes {
            duration = 375
            0f at 0 // ms  // Optional
            0.4f at 75 // ms
            0.4f at 225 // ms
            0f at 375 // ms  // Optional
        }
        interruptionHandling = InterruptionHandling.UNINTERRUPTIBLE
    }
}
Once a TransitionDefinition is created, androidx.ui.animation.Transition composable can takeit as an input and create a state-based transition in compose.

Summary

Public constructors

TransitionDefinition contains all the animation related configurations that will be used in a state-based transition.

Public methods

TransitionState
getStateFor(name: T)

Returns a state holder for the specific state name.

Unit
snapTransition(vararg fromToPairs: Pair<T?, T?>, nextState: T? = null)

With this transition definition we are saying that every time we reach the state 'from' we should immediately snap to 'to' state instead.

Unit
state(name: T, init: MutableTransitionState.() -> Unit)

Defines all the properties and their values associated with the state with the name: name The first state defined in the transition definition will be the default state, whose property values will be used as its initial values to createAnimation from.

Unit
transition(fromState: T? = null, toState: T? = null, init: TransitionSpec<T>.() -> Unit)

Defines a transition from state fromState to toState.

Unit
transition(vararg fromToPairs: Pair<T?, T?>, init: TransitionSpec<T>.() -> Unit)

Defines a transition from state first value to the second value of the fromToPairs.

Extension functions

From androidx.animation
TransitionAnimation<T>

Creates a transition animation using the transition definition and the given clock.

Set<T>

Returns the all states available in a TransitionDefinition.

Public constructors

<init>

TransitionDefinition()

TransitionDefinition contains all the animation related configurations that will be used in a state-based transition. It holds a set of TransitionStates and an optional set of TransitionSpecs. It can be used in android.ui.animation.Transition to create a state-based animation in Compose.

Each TransitionState specifies how the UI should look in terms of values associated with properties that differentiates the UI from one conceptual state to anther. Each TransitionState can be considered as a snapshot of the UI in the form of property values.

TransitionSpec defines how to animate from one state to another with a specific animation for each property defined in the states. TransitionSpec can be created using transition method inside of a TransitionDefinition. Currently the animations supported in a transition are: TransitionSpec.tween, TransitionSpec.keyframes, TransitionSpec.physics, TransitionSpec.snap, TransitionSpec.repeatable. When no TransitionSpec is specified, the default TransitionSpec.physics animation will be used for all properties involved. Similarly, when no animation is provided in a TransitionSpec for a particular property, the default physics animation will be used. For each transition, both the from and the to state can be omitted. Omitting in this case is equivalent to a wildcard on the starting state or ending state. When both are omitted at the same time, it means this transition applies to all the state transitions unless a more specific transition have been defined.

To create a TransitionDefinition, there are generally 3 steps involved:

Step 1: Create PropKeys. One PropKey is required for each property/value that needs to be animated. These should be file level properties, so they are visible to TransitionDefinition ( which will be created in step 3).

    val radius = FloatPropKey()
    val alpha = FloatPropKey()

Step 2 (optional): Create state names.

This is an optional but recommended step to create a reference for different states that the animation should end at. State names can be of type T, which means they can be string, integer, etc, or any custom object, so long as they are consistent.

It is recommended to either reuse the states that you already defined (e.g. TogglableState.On, TogglableState.Off, etc) for animating those state changes, or create an enum class for all the animation states.

    enum class ButtonState {
        Released, Pressed, Disabled
    }

Step 3: Create a TransitionDefinition using the animation DSL.

TransitionDefinition is conceptually an animation configuration that defines:

  1. States, each of which are described as a set of values. Each value is associated with a PropKey.
  2. Optional transitions, for how to animate from one state to another.
import androidx.animation.transitionDefinition

val definition = transitionDefinition {
    state(ButtonState.Pressed) {
        this[alpha] = 0f
        this[radius] = 200f
    }
    state(ButtonState.Released) {
        this[alpha] = 0f
        this[radius] = 60f
    }

    // Optional configuration for transition from Pressed to Released. If no transition is
    // defined, the default physics-based transition will be used.
    transition(fromState = ButtonState.Released, toState = ButtonState.Pressed) {
        radius using physics {
            dampingRatio = 1.0f
        }
        alpha using keyframes {
            duration = 375
            0f at 0 // ms  // Optional
            0.4f at 75 // ms
            0.4f at 225 // ms
            0f at 375 // ms  // Optional
        }
        interruptionHandling = InterruptionHandling.UNINTERRUPTIBLE
    }
}
Once a TransitionDefinition is created, androidx.ui.animation.Transition composable can takeit as an input and create a state-based transition in compose.

Public methods

getStateFor

fun getStateFor(name: T): TransitionState

Returns a state holder for the specific state name. Useful for the cases where we don't need actual animation to be happening like in tests.

snapTransition

fun snapTransition(
    vararg fromToPairs: Pair<T?, T?>,
    nextState: T? = null
): Unit

With this transition definition we are saying that every time we reach the state 'from' we should immediately snap to 'to' state instead.

Sample of usage with Pairs infix extension to: snapTransition(State.Released to State.Pressed)

Parameters
vararg fromToPairs: Pair<T?, T?> The pairs of states for this transition
nextState: T? = null Optional state where should we start switching after snap

state

fun state(
    name: T,
    init: MutableTransitionState.() -> Unit
): Unit

Defines all the properties and their values associated with the state with the name: name The first state defined in the transition definition will be the default state, whose property values will be used as its initial values to createAnimation from.

Note that the first MutableTransitionState created with state in a TransitionDefinition will be used as the initial state.

Parameters
name: T The name of the state, which can be used to createAnimation from or to this state
init: MutableTransitionState.() -> Unit Lambda to initialize a state

transition

fun transition(
    fromState: T? = null,
    toState: T? = null,
    init: TransitionSpec<T>.() -> Unit
): Unit

Defines a transition from state fromState to toState. When animating from one state to another, TransitionAnimation will find the most specific matching transition, and use the animations defined in it for the state transition. Both fromState and toState are optional. When undefined, it means a wildcard transition going from/to any state.

Parameters
fromState: T? = null The state that the transition will be animated from
toState: T? = null The state that the transition will be animated to
init: TransitionSpec<T>.() -> Unit Lambda to initialize the transition

transition

fun transition(
    vararg fromToPairs: Pair<T?, T?>,
    init: TransitionSpec<T>.() -> Unit
): Unit

Defines a transition from state first value to the second value of the fromToPairs. When animating from one state to another, TransitionAnimation will find the most specific matching transition, and use the animations defined in it for the state transition. Both values in the pair can be null. When they are null, it means a wildcard transition going from/to any state.

Sample of usage with Pairs infix extension to:

import androidx.animation.transitionDefinition

transitionDefinition<ButtonState> {
    transition(
        ButtonState.Released to ButtonState.Pressed,
        ButtonState.Disabled to ButtonState.Pressed
    ) {
        // ...
    }
}
Parameters
vararg fromToPairs: Pair<T?, T?> The pairs of from and to states for this transition
init: TransitionSpec<T>.() -> Unit Lambda to initialize the transition