LinearWavyProgressIndicator

Component in Material 3 Compose

Progress indicators express an unspecified wait time or display the duration of a process.

Last updated: 2024-10-22 13:47

Installation

dependencies {
   implementation("androidx.compose.material3:material3:1.4.0-alpha02")
}

Overloads

@ExperimentalMaterial3ExpressiveApi
@Composable
fun LinearWavyProgressIndicator(
    progress: () -> Float,
    modifier: Modifier = Modifier,
    color: Color = WavyProgressIndicatorDefaults.indicatorColor,
    trackColor: Color = WavyProgressIndicatorDefaults.trackColor,
    stroke: Stroke = WavyProgressIndicatorDefaults.linearIndicatorStroke,
    trackStroke: Stroke = WavyProgressIndicatorDefaults.linearTrackStroke,
    gapSize: Dp = WavyProgressIndicatorDefaults.LinearIndicatorTrackGapSize,
    stopSize: Dp = WavyProgressIndicatorDefaults.LinearTrackStopIndicatorSize,
    amplitude: (progress: Float) -> Float = WavyProgressIndicatorDefaults.indicatorAmplitude,
    wavelength: Dp = WavyProgressIndicatorDefaults.LinearDeterminateWavelength,
    waveSpeed: Dp = wavelength // Match to 1 wavelength per second
)

Parameters

name	description
progress	the progress of this progress indicator, where 0.0 represents no progress and 1.0 represents full progress. Values outside of this range are coerced into the range.
modifier	the [Modifier] to be applied to this progress indicator
color	the progress indicator color
trackColor	the indicator's track color, visible when the progress has not reached the area of the overall indicator yet
stroke	a [Stroke] that will be used to draw this indicator
trackStroke	a [Stroke] that will be used to draw the indicator's track
gapSize	the gap between the track and the progress parts of the indicator
stopSize	the size of the stop indicator at the end of the track. Note that the stop indicator is required if the track has a contrast below 3:1 with its container or the surface behind the container.
amplitude	a lambda that provides an amplitude for the wave path as a function of the indicator's progress. 0.0 represents no amplitude, and 1.0 represents an amplitude that will take the full height of the progress indicator. Values outside of this range are coerced into the range.
wavelength	the length of a wave. Will be applied in case the path has an [amplitude] that is greater than zero and represents a wave.
waveSpeed	the speed in which the wave will move when the [amplitude] is greater than zero. The value here represents a DP per seconds, and by default it's matched to the [wavelength] to render an animation that moves the wave by one wave length per second.

@ExperimentalMaterial3ExpressiveApi
@Composable
fun LinearWavyProgressIndicator(
    modifier: Modifier = Modifier,
    color: Color = WavyProgressIndicatorDefaults.indicatorColor,
    trackColor: Color = WavyProgressIndicatorDefaults.trackColor,
    stroke: Stroke = WavyProgressIndicatorDefaults.linearIndicatorStroke,
    trackStroke: Stroke = WavyProgressIndicatorDefaults.linearTrackStroke,
    gapSize: Dp = WavyProgressIndicatorDefaults.LinearIndicatorTrackGapSize,
    @FloatRange(from = 0.0, to = 1.0) amplitude: Float = 1f,
    wavelength: Dp = WavyProgressIndicatorDefaults.LinearIndeterminateWavelength,
    waveSpeed: Dp = wavelength // Match to 1 wavelength per second
)

Parameters

name	description
modifier	the [Modifier] to be applied to this progress indicator
color	the progress indicator color
trackColor	the indicator's track color, visible when the progress has not reached the area of the overall indicator yet
stroke	a [Stroke] that will be used to draw this indicator
trackStroke	a [Stroke] that will be used to draw the indicator's track
gapSize	the gap between the track and the progress parts of the indicator
amplitude	the wave's amplitude. 0.0 represents no amplitude, and 1.0 represents an amplitude that will take the full height of the progress indicator. Values outside of this range are coerced into the range.
wavelength	the length of a wave
waveSpeed	the speed in which the wave will move when the [amplitude] is greater than zero. The value here represents a DP per seconds, and by default it's matched to the [wavelength] to render an animation that moves the wave by one wave length per second.

Code Examples

LinearWavyProgressIndicatorSample

@OptIn(ExperimentalMaterial3ExpressiveApi::class)
@Preview
@Composable
fun LinearWavyProgressIndicatorSample() {
    var progress by remember { mutableFloatStateOf(0.1f) }
    val animatedProgress by
        animateFloatAsState(
            targetValue = progress,
            animationSpec = ProgressIndicatorDefaults.ProgressAnimationSpec
        )

    Column(horizontalAlignment = Alignment.CenterHorizontally) {
        LinearWavyProgressIndicator(
            progress = { animatedProgress },
        )
        Spacer(Modifier.requiredHeight(30.dp))
        Text("Set progress:")
        Slider(
            modifier = Modifier.width(300.dp),
            value = progress,
            valueRange = 0f..1f,
            onValueChange = { progress = it },
        )
    }
}

LinearThickWavyProgressIndicatorSample

@OptIn(ExperimentalMaterial3ExpressiveApi::class)
@Preview
@Composable
fun LinearThickWavyProgressIndicatorSample() {
    var progress by remember { mutableFloatStateOf(0.1f) }
    val animatedProgress by
        animateFloatAsState(
            targetValue = progress,
            animationSpec = ProgressIndicatorDefaults.ProgressAnimationSpec
        )

    val thickStrokeWidth = with(LocalDensity.current) { 8.dp.toPx() }
    val thickStroke =
        remember(thickStrokeWidth) { Stroke(width = thickStrokeWidth, cap = StrokeCap.Round) }

    Column(horizontalAlignment = Alignment.CenterHorizontally) {
        LinearWavyProgressIndicator(
            progress = { animatedProgress },
            // Thick height is slightly higher than the
            // WavyProgressIndicatorDefaults.LinearContainerHeight default
            modifier = Modifier.height(14.dp),
            stroke = thickStroke,
            trackStroke = thickStroke,
        )
        Spacer(Modifier.requiredHeight(30.dp))
        Text("Set progress:")
        Slider(
            modifier = Modifier.width(300.dp),
            value = progress,
            valueRange = 0f..1f,
            onValueChange = { progress = it },
        )
    }
}

IndeterminateLinearWavyProgressIndicatorSample

@OptIn(ExperimentalMaterial3ExpressiveApi::class)
@Preview
@Composable
fun IndeterminateLinearWavyProgressIndicatorSample() {
    Column(horizontalAlignment = Alignment.CenterHorizontally) { LinearWavyProgressIndicator() }
}