# AnimatedText

## Functions summary

|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable @https://developer.android.com/reference/kotlin/androidx/annotation/RequiresApi(value = 31) https://developer.android.com/reference/kotlin/androidx/wear/compose/material3/AnimatedText.composable#AnimatedText(kotlin.String,androidx.wear.compose.material3.AnimatedTextFontRegistry,kotlin.Function0,androidx.compose.ui.Modifier,androidx.compose.ui.Alignment)( text: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, fontRegistry: https://developer.android.com/reference/kotlin/androidx/wear/compose/material3/AnimatedTextFontRegistry, progressFraction: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier, contentAlignment: https://developer.android.com/reference/kotlin/androidx/compose/ui/Alignment )` A composable that displays an animated text. |

## Functions

### AnimatedText

Artifact: [androidx.wear.compose:compose-material3](https://developer.android.com/jetpack/androidx/releases/wear-compose) [View Source](https://cs.android.com/search?q=file:androidx/wear/compose/material3/AnimatedText.kt+function:AnimatedText) Added in [1.5.0](https://developer.android.com/jetpack/androidx/releases/wear-compose#1.5.0)

```
@Composable
@RequiresApi(value = 31)
fun AnimatedText(
    text: String,
    fontRegistry: AnimatedTextFontRegistry,
    progressFraction: () -> Float,
    modifier: Modifier = Modifier,
    contentAlignment: Alignment = Alignment.Center
): Unit
```

A composable that displays an animated text.

AnimatedText can be used to animate a text along font variation axes and size. It requires an `https://developer.android.com/reference/kotlin/androidx/wear/compose/material3/AnimatedTextFontRegistry` to improve performance.

`https://developer.android.com/reference/kotlin/androidx/wear/compose/material3/AnimatedTextFontRegistry` can be generated using `https://developer.android.com/reference/kotlin/androidx/wear/compose/material3/rememberAnimatedTextFontRegistry.composable#rememberAnimatedTextFontRegistry(androidx.compose.ui.text.font.FontVariation.Settings,androidx.compose.ui.text.font.FontVariation.Settings,androidx.compose.ui.text.TextStyle,androidx.compose.ui.unit.TextUnit,androidx.compose.ui.unit.TextUnit)` method, which requires start and end font variation axes, and start and end font sizes for the animation.

Start of the animation is when the animatable is at 0f and end of the animation is when the animatable is at 1f. Current animation progress is provided by the `https://developer.android.com/reference/kotlin/androidx/wear/compose/material3/package-summary#AnimatedText(kotlin.String,androidx.wear.compose.material3.AnimatedTextFontRegistry,kotlin.Function0,androidx.compose.ui.Modifier,androidx.compose.ui.Alignment)` function. This should be between 0f and 1f, but might go beyond in some cases such as overshooting spring animations.

Example of a one-shot animation with AnimatedText

```kotlin
import androidx.compose.animation.core.Animatable
import androidx.compose.foundation.clickable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.font.FontVariation
import androidx.compose.ui.unit.sp
import androidx.wear.compose.material3.AnimatedText
import androidx.wear.compose.material3.Text
import androidx.wear.compose.material3.rememberAnimatedTextFontRegistry

val scope = rememberCoroutineScope()
val animatable = remember { Animatable(0f) }
val animate = {
    scope.launch {
        // Animate from 0 to 1 and then back to 0.
        animatable.animateTo(1f)
        animatable.animateTo(0f)
    }
}
val animatedTextFontRegistry =
    rememberAnimatedTextFontRegistry(
        // Variation axes at the start of the animation, width 10, weight 200
        startFontVariationSettings =
            FontVariation.Settings(FontVariation.width(10f), FontVariation.weight(200)),
        // Variation axes at the end of the animation, width 100, weight 500
        endFontVariationSettings =
            FontVariation.Settings(FontVariation.width(100f), FontVariation.weight(500)),
        startFontSize = 30.sp,
        endFontSize = 40.sp,
    )
AnimatedText(
    text = "Hello!",
    fontRegistry = animatedTextFontRegistry,
    // Content alignment anchors the animation at the vertical center, expanding horizontally
    contentAlignment = Alignment.CenterStart,
    progressFraction = { animatable.value },
    modifier = Modifier.clickable(onClick = { animate() }),
)
LaunchedEffect(Unit) { animate() }
```

Example of an animation in response to a button press with AnimatedText

```kotlin
import androidx.compose.animation.core.Animatable
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.padding
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.semantics.contentDescription
import androidx.compose.ui.semantics.semantics
import androidx.compose.ui.text.font.FontVariation
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
import androidx.wear.compose.material3.AnimatedText
import androidx.wear.compose.material3.Button
import androidx.wear.compose.material3.Text
import androidx.wear.compose.material3.rememberAnimatedTextFontRegistry

val scope = rememberCoroutineScope()
val animatedTextFontRegistry =
    rememberAnimatedTextFontRegistry(
        // Variation axes at the start of the animation, width 10, weight 200
        startFontVariationSettings =
            FontVariation.Settings(FontVariation.width(10f), FontVariation.weight(200)),
        // Variation axes at the end of the animation, width 100, weight 500
        endFontVariationSettings =
            FontVariation.Settings(FontVariation.width(100f), FontVariation.weight(500)),
        startFontSize = 30.sp,
        endFontSize = 30.sp,
    )
val number = remember { mutableIntStateOf(0) }
val textAnimatable = remember { Animatable(0f) }
Row(verticalAlignment = Alignment.CenterVertically) {
    Button(
        modifier = Modifier.padding(horizontal = 16.dp),
        onClick = {
            number.value -= 1
            scope.launch {
                textAnimatable.animateTo(1f)
                textAnimatable.animateTo(0f)
            }
        },
        label = {
            Text(modifier = Modifier.semantics { contentDescription = "Decrease" }, text = "-")
        },
    )
    AnimatedText(
        text = "${number.value}",
        fontRegistry = animatedTextFontRegistry,
        progressFraction = { textAnimatable.value },
    )
    Button(
        modifier = Modifier.padding(horizontal = 16.dp),
        onClick = {
            number.value += 1
            scope.launch {
                textAnimatable.animateTo(1f)
                textAnimatable.animateTo(0f)
            }
        },
        label = {
            Text(modifier = Modifier.semantics { contentDescription = "Increase" }, text = "+")
        },
    )
}
```

Example showing how `https://developer.android.com/reference/kotlin/androidx/wear/compose/material3/AnimatedTextFontRegistry` can be reused and shared between two `https://developer.android.com/reference/kotlin/androidx/wear/compose/material3/AnimatedText.composable#AnimatedText(kotlin.String,androidx.wear.compose.material3.AnimatedTextFontRegistry,kotlin.Function0,androidx.compose.ui.Modifier,androidx.compose.ui.Alignment)` composables

```kotlin
import androidx.compose.animation.core.Animatable
import androidx.compose.foundation.layout.Column
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.text.font.FontVariation
import androidx.compose.ui.unit.sp
import androidx.wear.compose.material3.AnimatedText
import androidx.wear.compose.material3.Text
import androidx.wear.compose.material3.rememberAnimatedTextFontRegistry

val animatedTextFontRegistry =
    rememberAnimatedTextFontRegistry(
        // Variation axes at the start of the animation, width 50, weight 300
        startFontVariationSettings =
            FontVariation.Settings(FontVariation.width(50f), FontVariation.weight(300)),
        // Variation axes at the end of the animation are the same as the start axes
        endFontVariationSettings =
            FontVariation.Settings(FontVariation.width(50f), FontVariation.weight(300)),
        startFontSize = 15.sp,
        endFontSize = 25.sp,
    )
val firstAnimatable = remember { Animatable(0f) }
val secondAnimatable = remember { Animatable(0f) }
Column(horizontalAlignment = Alignment.CenterHorizontally) {
    AnimatedText(
        text = "Top Text",
        fontRegistry = animatedTextFontRegistry,
        progressFraction = { firstAnimatable.value },
    )
    AnimatedText(
        text = "Bottom Text",
        fontRegistry = animatedTextFontRegistry,
        progressFraction = { secondAnimatable.value },
    )
}
LaunchedEffect(Unit) {
    firstAnimatable.animateTo(1f)
    firstAnimatable.animateTo(0f)
    secondAnimatable.animateTo(1f)
    secondAnimatable.animateTo(0f)
}
```

| Parameters |
|---|---|
| `text: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The text to be displayed. |
| `fontRegistry: https://developer.android.com/reference/kotlin/androidx/wear/compose/material3/AnimatedTextFontRegistry` | The font registry to be used to animate the text. |
| `progressFraction: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html` | A provider for the current state of the animation. Provided value should be between 0f and 1f, but might go beyond in some cases such as overshooting spring animations. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier = Modifier` | Modifier to be applied to the composable. |
| `contentAlignment: https://developer.android.com/reference/kotlin/androidx/compose/ui/Alignment = Alignment.Center` | Alignment within the bounds of the Canvas. |