FadingExpandingLabel

Component in Wear Material 3 Compose

Animates label text for which the number of lines can vary, changing the size of the container component.

Displays the given string in a [Text], with an animation that fades text in line by line when new lines of text are added or removed. This is intended to be be used for labels in a Button or Card, where we want the container to expand to fit the contents when the lines of the text change.

Last updated: 2025-03-21 11:59

Installation

dependencies {
   implementation("androidx.wear.compose:compose-material3:1.0.0-alpha34")
}

Overloads

@Composable
fun FadingExpandingLabel(
    text: String,
    modifier: Modifier = Modifier,
    color: Color = Color.Unspecified,
    fontSize: TextUnit = TextUnit.Unspecified,
    fontStyle: FontStyle? = null,
    fontWeight: FontWeight? = null,
    fontFamily: FontFamily? = null,
    letterSpacing: TextUnit = TextUnit.Unspecified,
    textDecoration: TextDecoration? = null,
    textAlign: TextAlign? = LocalTextConfiguration.current.textAlign,
    lineHeight: TextUnit = TextUnit.Unspecified,
    softWrap: Boolean = true,
    maxLines: Int = LocalTextConfiguration.current.maxLines,
    minLines: Int = 1,
    textStyle: TextStyle = LocalTextStyle.current,
    animationSpec: FiniteAnimationSpec<Float> = FadingExpandingLabelDefaults.animationSpec,
)

Parameters

name	description
text	Text string that will be shown.
modifier	Modifier to be applied to the animated text.
color	[Color] to apply to the text. If [Color.Unspecified], and [textStyle] has no color set,this will be [LocalContentColor].
fontSize	The size of glyphs to use when painting the text. See [TextStyle.fontSize].
fontStyle	The typeface variant to use when drawing the letters (e.g., italic). See [TextStyle.fontStyle].
fontWeight	The typeface thickness to use when painting the text (e.g., [FontWeight.Bold]).
fontFamily	The font family to be used when rendering the text. See [TextStyle.fontFamily].
letterSpacing	The amount of space to add between each letter. See [TextStyle.letterSpacing].
textDecoration	The decorations to paint on the text (e.g., an underline). See [TextStyle.textDecoration].
textAlign	The alignment of the text within the lines of the paragraph. See [TextStyle.textAlign].
lineHeight	Line height for the [Paragraph] in [TextUnit] unit, e.g. SP or EM. See [TextStyle.lineHeight].
softWrap	Whether the text should break at soft line breaks. If false, the glyphs in the text will be positioned as if there was unlimited horizontal space. If [softWrap] is false, TextAlign may have unexpected effects.
maxLines	An optional maximum number of lines for the text to span, wrapping if necessary. If it is not null, then it must be greater than zero.
minLines	The minimum height in terms of minimum number of visible lines. It is required that 1 {'<='} [minLines] {'<='} [maxLines].
textStyle	[TextStyle] for the animated text.
animationSpec	Animation spec for the text fade animation.

Code Example

FadingExpandingLabelButtonSample

@Composable
fun FadingExpandingLabelButtonSample() {
    var text by remember { mutableStateOf("Line 1") }
    var lines by remember { mutableIntStateOf(1) }

    Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
        Button(
            onClick = {
                lines = lines % 3 + 1
                text = (1..lines).joinToString(separator = "\n") { "Line $it" }
            },
            modifier = Modifier.fillMaxWidth(),
            label = { FadingExpandingLabel(text = text) }
        )
    }
}