CircularProgressIndicator

Component in Wear Material 3 Compose

Material Design circular progress indicator.

Last updated: 2024-09-07 14:23

Installation

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

Overloads

@Composable
fun CircularProgressIndicator(
    progress: () -> Float,
    modifier: Modifier = Modifier,
    startAngle: Float = CircularProgressIndicatorDefaults.StartAngle,
    endAngle: Float = startAngle,
    colors: ProgressIndicatorColors = ProgressIndicatorDefaults.colors(),
    strokeWidth: Dp = CircularProgressIndicatorDefaults.largeStrokeWidth,
    gapSize: Dp = CircularProgressIndicatorDefaults.calculateRecommendedGapSize(strokeWidth),
    enabled: Boolean = true,
)

Parameters

name	description
progress	The progress of this progress indicator where 0.0 represents no progress and 1.0 represents completion. Values outside of this range are coerced into the range 0..1.
modifier	Modifier to be applied to the CircularProgressIndicator.
startAngle	The starting position of the progress arc, measured clockwise in degrees (0 to 360) from the 3 o'clock position. For example, 0 and 360 represent 3 o'clock, 90 and 180 represent 6 o'clock and 9 o'clock respectively. Default is 270 degrees [CircularProgressIndicatorDefaults.StartAngle] (top of the screen).
endAngle	The ending position of the progress arc, measured clockwise in degrees (0 to 360) from the 3 o'clock position. For example, 0 and 360 represent 3 o'clock, 90 and 180 represent 6 o'clock and 9 o'clock respectively. By default equal to [startAngle].
colors	[ProgressIndicatorColors] that will be used to resolve the indicator and track color for this progress indicator in different states.
strokeWidth	The stroke width for the progress indicator. The recommended values are [CircularProgressIndicatorDefaults.largeStrokeWidth] and [CircularProgressIndicatorDefaults.smallStrokeWidth].
gapSize	The size (in Dp) of the gap between the ends of the progress indicator and the track. The stroke endcaps are not included in this distance.
enabled	controls the enabled state. Although this component is not clickable, it can be contained within a clickable component. When enabled is false, this component will appear visually disabled.

Code Examples

FullScreenProgressIndicatorSample

@Composable
fun FullScreenProgressIndicatorSample() {
    Box(
        modifier =
            Modifier.background(MaterialTheme.colorScheme.background)
                .padding(CircularProgressIndicatorDefaults.FullScreenPadding)
                .fillMaxSize()
    ) {
        CircularProgressIndicator(
            progress = { 0.25f },
            startAngle = 120f,
            endAngle = 60f,
            colors =
                ProgressIndicatorDefaults.colors(
                    indicatorColor = Color.Green,
                    trackColor = Color.Green.copy(alpha = 0.5f)
                )
        )
    }
}

OverflowProgressIndicatorSample

@Composable
fun OverflowProgressIndicatorSample() {
    Box(
        modifier =
            Modifier.background(MaterialTheme.colorScheme.background)
                .padding(CircularProgressIndicatorDefaults.FullScreenPadding)
                .fillMaxSize()
    ) {
        CircularProgressIndicator(
            // The progress is limited by 100%, 120% ends up being 20% with the track brush
            // indicating overflow.
            progress = { 0.2f },
            startAngle = 120f,
            endAngle = 60f,
            colors =
                ProgressIndicatorDefaults.colors(
                    trackBrush =
                        Brush.linearGradient(
                            listOf(
                                MaterialTheme.colorScheme.primary,
                                MaterialTheme.colorScheme.surfaceContainer
                            )
                        )
                )
        )
    }
}

MediaButtonProgressIndicatorSample

@Composable
fun MediaButtonProgressIndicatorSample() {
    var isPlaying by remember { mutableStateOf(false) }
    val progressPadding = 4.dp
    val progress = 0.75f

    Box(modifier = Modifier.fillMaxSize().background(MaterialTheme.colorScheme.background)) {
        Box(
            modifier =
                Modifier.align(Alignment.Center)
                    .size(IconButtonDefaults.DefaultButtonSize + progressPadding)
        ) {
            CircularProgressIndicator(progress = { progress }, strokeWidth = progressPadding)
            IconButton(
                modifier =
                    Modifier.align(Alignment.Center)
                        .semantics {
                            // Set custom progress semantics for accessibility.
                            contentDescription =
                                String.format(
                                    "Play/pause button, track progress: %.0f%%",
                                    progress * 100
                                )
                        }
                        .padding(progressPadding)
                        .clip(CircleShape)
                        .background(MaterialTheme.colorScheme.surfaceContainerLow),
                onClick = { isPlaying = !isPlaying }
            ) {
                Icon(
                    imageVector = if (isPlaying) Icons.Filled.Close else Icons.Filled.PlayArrow,
                    contentDescription = null,
                )
            }
        }
    }
}

SmallValuesProgressIndicatorSample

@Composable
fun SmallValuesProgressIndicatorSample() {
    Box {
        CircularProgressIndicator(
            // Small progress values like 2% will be rounded up to at least the stroke width.
            progress = { 0.02f },
            modifier =
                Modifier.fillMaxSize().padding(CircularProgressIndicatorDefaults.FullScreenPadding),
            startAngle = 120f,
            endAngle = 60f,
            strokeWidth = 10.dp,
            colors =
                ProgressIndicatorDefaults.colors(
                    indicatorColor = Color.Green,
                    trackColor = Color.White
                ),
        )
    }
}