# HorizontalSharedAxisNavigationTransitions

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

## API Reference

> Source set: Common

```kotlin
public object 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](https://m3.material.io/styles/motion/transitions/transition-patterns).

## Properties

### scrimColor

> Source set: Common

```kotlin
public 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`.

## Functions

### forwardTransform

> Source set: Common

```kotlin
public fun forwardTransform(): ContentTransform
```

Creates a `ContentTransform` for a forward horizontal shared axis transition.

### backwardTransform

> Source set: Common

```kotlin
public fun backwardTransform(): ContentTransform
```

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

### predictiveBackTransform

> Source set: Common

```kotlin
public 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.

#### Parameters

| | |
| --- | --- |
| backEvent | provider of the ongoing `NavigationEvent`. |
| density | the [Density](https://composables.com/jetpack-compose/androidx.compose.ui/ui-unit/interfaces/Density/api.md) used to convert display bounds margins to pixels. |
| scrimColor | color of the scrim overlay applied to the entering content. Use [HorizontalSharedAxisNavigationTransitions.scrimColor](https://composables.com/jetpack-compose/androidx.compose.material3/material3/objects/HorizontalSharedAxisNavigationTransitions/api.md) for the recommended scrim color that adapts to the theme. |

## Code Examples

### HorizontalSharedAxisTransitionSample

```kotlin
@Preview
@Sampled
@Composable
fun HorizontalSharedAxisTransitionSample() {
    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)
            }
        }
    }
}
```
