HorizontalSharedAxisNavigationTransitions


Provides horizontal shared axis navigation transforms adhering to Material 3 motion specifications.

Use these animations for transitions between destinations with a spatial or directional relationship, such as moving forward and backward through a screen hierarchy or sequential flow. Incoming and outgoing destinations move simultaneously along a shared horizontal (x) axis to reinforce their spatial relationship.

These animations are consistent with the default system cross-activity navigation animations. See Material 3 transition patterns.

import androidx.compose.animation.DeferredAnimatedContent
import androidx.compose.animation.core.DeferredTransitionState
import androidx.compose.animation.core.rememberDeferredTransition
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.HorizontalSharedAxisNavigationTransitions
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Surface
import androidx.compose.material3.Text
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalDensity
import androidx.compose.ui.unit.dp
import androidx.navigationevent.NavigationEvent

var targetScreen by remember { mutableIntStateOf(1) }
var isGestureInProgress by remember { mutableStateOf(false) }
var backEvent by remember { mutableStateOf(NavigationEvent()) }

// TODO(b/561731740): Replace this manual navigation setup with NavDisplay once it adopts
//  MutableContentTransform, which provides built-in transition and back gesture handling.
val transitionState = remember { DeferredTransitionState(targetScreen) }
val transition = rememberDeferredTransition(transitionState)

LaunchedEffect(isGestureInProgress, targetScreen) {
    if (isGestureInProgress) {
        transitionState.defer(targetScreen)
    } else {
        transitionState.animateTo(targetScreen)
    }
}

val scrimColor = HorizontalSharedAxisNavigationTransitions.scrimColor
val density = LocalDensity.current

transition.DeferredAnimatedContent(
    transitionSpec = {
        if (targetState > initialState) {
            HorizontalSharedAxisNavigationTransitions.forwardTransform()
        } else {
            HorizontalSharedAxisNavigationTransitions.backwardTransform()
        }
    },
    mutableTransformSpec = {
        if (initialState > targetState) {
            HorizontalSharedAxisNavigationTransitions.predictiveBackTransform(
                backEvent = { backEvent },
                density = density,
                scrimColor = scrimColor,
            )
        } else {
            null
        }
    },
) { screen ->
    Surface(
        modifier = Modifier.fillMaxSize(),
        color =
            if (screen == 1) {
                MaterialTheme.colorScheme.primaryContainer
            } else {
                MaterialTheme.colorScheme.secondaryContainer
            },
    ) {
        Box(Modifier.fillMaxSize().padding(16.dp), contentAlignment = Alignment.Center) {
            Text("Screen $screen", style = MaterialTheme.typography.headlineLarge)
        }
    }
}

Summary

Public functions

ContentTransform

Creates a ContentTransform for the commit phase of a horizontal shared axis backward transition.

Cmn
ContentTransform

Creates a ContentTransform for a forward horizontal shared axis transition.

Cmn
MutableContentTransform
predictiveBackTransform(
    backEvent: () -> NavigationEvent,
    density: Density,
    scrimColor: Color
)

Creates a MutableContentTransform configured for the gesture phase of a horizontal shared axis predictive back transition.

Cmn

Public properties

Color

The recommended scrim color for horizontal shared axis predictive back transitions.

Cmn

Public functions

backwardTransform

fun backwardTransform(): ContentTransform

Creates a ContentTransform for the commit phase of a horizontal shared axis backward transition.

import androidx.compose.animation.DeferredAnimatedContent
import androidx.compose.animation.core.DeferredTransitionState
import androidx.compose.animation.core.rememberDeferredTransition
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.HorizontalSharedAxisNavigationTransitions
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Surface
import androidx.compose.material3.Text
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalDensity
import androidx.compose.ui.unit.dp
import androidx.navigationevent.NavigationEvent

var targetScreen by remember { mutableIntStateOf(1) }
var isGestureInProgress by remember { mutableStateOf(false) }
var backEvent by remember { mutableStateOf(NavigationEvent()) }

// TODO(b/561731740): Replace this manual navigation setup with NavDisplay once it adopts
//  MutableContentTransform, which provides built-in transition and back gesture handling.
val transitionState = remember { DeferredTransitionState(targetScreen) }
val transition = rememberDeferredTransition(transitionState)

LaunchedEffect(isGestureInProgress, targetScreen) {
    if (isGestureInProgress) {
        transitionState.defer(targetScreen)
    } else {
        transitionState.animateTo(targetScreen)
    }
}

val scrimColor = HorizontalSharedAxisNavigationTransitions.scrimColor
val density = LocalDensity.current

transition.DeferredAnimatedContent(
    transitionSpec = {
        if (targetState > initialState) {
            HorizontalSharedAxisNavigationTransitions.forwardTransform()
        } else {
            HorizontalSharedAxisNavigationTransitions.backwardTransform()
        }
    },
    mutableTransformSpec = {
        if (initialState > targetState) {
            HorizontalSharedAxisNavigationTransitions.predictiveBackTransform(
                backEvent = { backEvent },
                density = density,
                scrimColor = scrimColor,
            )
        } else {
            null
        }
    },
) { screen ->
    Surface(
        modifier = Modifier.fillMaxSize(),
        color =
            if (screen == 1) {
                MaterialTheme.colorScheme.primaryContainer
            } else {
                MaterialTheme.colorScheme.secondaryContainer
            },
    ) {
        Box(Modifier.fillMaxSize().padding(16.dp), contentAlignment = Alignment.Center) {
            Text("Screen $screen", style = MaterialTheme.typography.headlineLarge)
        }
    }
}

forwardTransform

fun forwardTransform(): ContentTransform

Creates a ContentTransform for a forward horizontal shared axis transition.

import androidx.compose.animation.DeferredAnimatedContent
import androidx.compose.animation.core.DeferredTransitionState
import androidx.compose.animation.core.rememberDeferredTransition
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.HorizontalSharedAxisNavigationTransitions
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Surface
import androidx.compose.material3.Text
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalDensity
import androidx.compose.ui.unit.dp
import androidx.navigationevent.NavigationEvent

var targetScreen by remember { mutableIntStateOf(1) }
var isGestureInProgress by remember { mutableStateOf(false) }
var backEvent by remember { mutableStateOf(NavigationEvent()) }

// TODO(b/561731740): Replace this manual navigation setup with NavDisplay once it adopts
//  MutableContentTransform, which provides built-in transition and back gesture handling.
val transitionState = remember { DeferredTransitionState(targetScreen) }
val transition = rememberDeferredTransition(transitionState)

LaunchedEffect(isGestureInProgress, targetScreen) {
    if (isGestureInProgress) {
        transitionState.defer(targetScreen)
    } else {
        transitionState.animateTo(targetScreen)
    }
}

val scrimColor = HorizontalSharedAxisNavigationTransitions.scrimColor
val density = LocalDensity.current

transition.DeferredAnimatedContent(
    transitionSpec = {
        if (targetState > initialState) {
            HorizontalSharedAxisNavigationTransitions.forwardTransform()
        } else {
            HorizontalSharedAxisNavigationTransitions.backwardTransform()
        }
    },
    mutableTransformSpec = {
        if (initialState > targetState) {
            HorizontalSharedAxisNavigationTransitions.predictiveBackTransform(
                backEvent = { backEvent },
                density = density,
                scrimColor = scrimColor,
            )
        } else {
            null
        }
    },
) { screen ->
    Surface(
        modifier = Modifier.fillMaxSize(),
        color =
            if (screen == 1) {
                MaterialTheme.colorScheme.primaryContainer
            } else {
                MaterialTheme.colorScheme.secondaryContainer
            },
    ) {
        Box(Modifier.fillMaxSize().padding(16.dp), contentAlignment = Alignment.Center) {
            Text("Screen $screen", style = MaterialTheme.typography.headlineLarge)
        }
    }
}

predictiveBackTransform

fun predictiveBackTransform(
    backEvent: () -> NavigationEvent,
    density: Density,
    scrimColor: Color
): MutableContentTransform

Creates a MutableContentTransform configured for the gesture phase of a horizontal shared axis predictive back transition.

import androidx.compose.animation.DeferredAnimatedContent
import androidx.compose.animation.core.DeferredTransitionState
import androidx.compose.animation.core.rememberDeferredTransition
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.HorizontalSharedAxisNavigationTransitions
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Surface
import androidx.compose.material3.Text
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalDensity
import androidx.compose.ui.unit.dp
import androidx.navigationevent.NavigationEvent

var targetScreen by remember { mutableIntStateOf(1) }
var isGestureInProgress by remember { mutableStateOf(false) }
var backEvent by remember { mutableStateOf(NavigationEvent()) }

// TODO(b/561731740): Replace this manual navigation setup with NavDisplay once it adopts
//  MutableContentTransform, which provides built-in transition and back gesture handling.
val transitionState = remember { DeferredTransitionState(targetScreen) }
val transition = rememberDeferredTransition(transitionState)

LaunchedEffect(isGestureInProgress, targetScreen) {
    if (isGestureInProgress) {
        transitionState.defer(targetScreen)
    } else {
        transitionState.animateTo(targetScreen)
    }
}

val scrimColor = HorizontalSharedAxisNavigationTransitions.scrimColor
val density = LocalDensity.current

transition.DeferredAnimatedContent(
    transitionSpec = {
        if (targetState > initialState) {
            HorizontalSharedAxisNavigationTransitions.forwardTransform()
        } else {
            HorizontalSharedAxisNavigationTransitions.backwardTransform()
        }
    },
    mutableTransformSpec = {
        if (initialState > targetState) {
            HorizontalSharedAxisNavigationTransitions.predictiveBackTransform(
                backEvent = { backEvent },
                density = density,
                scrimColor = scrimColor,
            )
        } else {
            null
        }
    },
) { screen ->
    Surface(
        modifier = Modifier.fillMaxSize(),
        color =
            if (screen == 1) {
                MaterialTheme.colorScheme.primaryContainer
            } else {
                MaterialTheme.colorScheme.secondaryContainer
            },
    ) {
        Box(Modifier.fillMaxSize().padding(16.dp), contentAlignment = Alignment.Center) {
            Text("Screen $screen", style = MaterialTheme.typography.headlineLarge)
        }
    }
}
Parameters
backEvent: () -> NavigationEvent

provider of the ongoing NavigationEvent.

density: Density

the Density used to convert display bounds margins to pixels.

scrimColor: Color

color of the scrim overlay applied to the entering content. Use HorizontalSharedAxisNavigationTransitions.scrimColor for the recommended scrim color that adapts to the theme.

Public properties

scrimColor

val scrimColor: Color

The recommended scrim color for horizontal shared axis predictive back transitions.

Uses ColorScheme.scrim as the base color and adjusts its opacity based on the luminance of ColorScheme.onSurface.