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

Change: trace

A comet-like stroke runs once around an element's outline when a value changes.

Trace sends a short, bright stroke with a fading tail once around the element’s outline, then lets it disappear. Use it to confirm that something finished in place, such as a sync, a save or a successful scan, without covering the content.

Usage

The sample traces a rounded card each time a backup finishes. Pass the same shape the card is clipped to, so the stroke follows its corners.

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.ChangeEffect
import com.jantursky.kapow.changeEffect
import kotlin.time.Duration.Companion.milliseconds

@Composable
fun BackupCard(backups: Int) {
    val shape = RoundedCornerShape(16.dp)
    Box(
        Modifier
            .size(240.dp, 110.dp)
            .changeEffect(backups, ChangeEffect.trace(shape, Color(0xFF6B62F2), duration = 900.milliseconds))
            .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. The head has a lighter core and a soft glow in the same color.
width 3.dp Width of the stroke at the head. The tail thins out towards its end. Must be positive.
duration 1.seconds How long the whole run takes, for all laps. Must be positive.
tail 0.4f How long the comet’s tail is, as a fraction of the outline, from 0 to 1.
clockwise true Whether the comet runs clockwise. Otherwise it runs the other way round.
startAt 0f Where the comet starts, as a fraction of the way round the outline from its usual start, from 0 to 1.
laps 1 How many times the comet goes around. duration covers all of them. Must be positive.
easing FastOutSlowInEasing The curve of the run.
headGlow 1f How strong the faint wide light under the comet’s head is, as a factor on the standard. 0 leaves it out.
brush null Draws the stroke instead of color, so the comet can be a gradient. The head’s bright core stays white.

Reduced motion

Nothing travels. The whole outline appears at once and fades out over 0.4 s. With reducedMotion(ReducedMotionMode.EndState) nothing shows at all, since the effect ends at rest.

Notes

  • For rectangles and rounded shapes, including CircleShape, the stroke starts at the middle of the top edge and runs clockwise. Other shapes start where their path starts.
  • The stroke sits just inside the element’s bounds, half its width in from the edge, so a parent that clips to the bounds does not cut it.
  • The tail is 40 % of the outline long. The head runs on past the starting point until the tail has caught up, so nothing is left behind.
  • The effect has a cooldown of half its duration. A change that arrives sooner after the last accepted one is ignored.
  • Progress trace draws the same outline up to a progress you control.

Live example

Was this page helpful?