Skip to content
Kapow
Esc
↑↓navigate↵open⌘Jpreview
On this page

Progress: trace

An element's outline drawn as a stroke up to a progress value.

Progress trace draws the element’s outline as a stroke that grows with a value you control: nothing at 0, the closed outline at 1. Use it as a progress ring around a card, an avatar or a button, for an upload or a countdown.

Usage

The sample draws the outline of a rounded upload card as progress goes from 0 to 1. Pass the shape the card is clipped to.

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.clip
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import com.jantursky.kapow.ProgressEffect
import com.jantursky.kapow.progressEffect

@Composable
fun UploadCard(progress: () -> Float) {
    val shape = RoundedCornerShape(24.dp)
    Box(
        Modifier
            .size(240.dp, 140.dp)
            .progressEffect(ProgressEffect.trace(shape, Color(0xFF6B62F2), width = 4.dp), progress)
            .clip(shape)
            .background(Color(0xFF161616)),
    )
}

Parameters

Parameter Default Description
shape RectangleShape The outline the stroke follows. Use the shape the element is clipped to.
color Color(0xFF6B62F2) Color of the stroke.
width 3.dp Width of the stroke. Must be positive.
brush null Strokes the outline instead of color, such as a gradient.
clockwise true Whether the trace goes round clockwise.
start 0f Where the trace starts, as a share of the way round the outline, from 0 to 1. 0 is the middle of the top edge, 0.25 the middle of the right edge.
tail 1f How much of the outline the stroke covers behind its head, above 0 and up to 1. 1 keeps everything from the start; less leaves a short stroke that travels.
cap StrokeCap.Round The ends of the stroke.

Reduced motion

Progress effects do not animate on their own. The outline is drawn as far as the progress says.

Notes

  • For rectangles and rounded shapes, including CircleShape, the stroke starts at the middle of the top edge and runs clockwise, like a clock hand. Other shapes start where their path starts.
  • The growing end is rounded. At progress 1 the outline closes without a seam.
  • The stroke sits just inside the element’s bounds, half its width in from the edge.
  • The outline is measured once per size, so a progress that changes every frame only cuts a new piece of the same path.
  • Change trace runs a comet along the same outline once when a value changes.

Live example

Was this page helpful?