Skip to content

maxrave-dev/kotlin-footguns / skills/compose-screens-footguns

compose-screens-footguns

Verified

Compose screen and interaction traps: navigation, adaptive layout, window insets, pagers, toolbars, sheets, list drag and selection, sliders, text fields, settings UI, one-shot effects. Use when layout, gestures or navigation misbehave.

FileKindSize
SKILL.mdskill md21.6 KB
references/collapsing-parallax-toolbar.mdmarkdown8.4 KB
references/commit-a-text-field-on-an-explicit-action.mdmarkdown8.1 KB
references/control-range-must-cover-stored-values.mdmarkdown6.2 KB
references/custom-modal-sheet-family.mdmarkdown7.1 KB
references/custom-thin-media-slider.mdmarkdown8.3 KB
references/desktop-mini-player-window.mdmarkdown7.8 KB
references/edit-a-shape-as-a-shape.mdmarkdown7.1 KB
references/empty-state-must-keep-its-navigation.mdmarkdown7.0 KB
references/event-not-state-edge-for-one-shot-effects.mdmarkdown7.5 KB
references/expandable-and-linkified-text.mdmarkdown6.9 KB
references/floating-overlay-reserves-its-own-strip.mdmarkdown9.1 KB
references/fullscreen-video-gesture-overlay.mdmarkdown7.6 KB
references/hidden-setting-does-not-clear-the-stored-value.mdmarkdown6.3 KB
references/layered-video-backdrop-pager.mdmarkdown8.6 KB
references/lazy-item-grouping-beats-arrangement-gap.mdmarkdown8.2 KB
references/lazy-list-drag-reorder.mdmarkdown8.0 KB
references/lazy-scroll-helper-kit.mdmarkdown6.9 KB
references/nav-tab-registration-drift.mdmarkdown8.6 KB
references/nowplaying-pager-no-feedback-loop.mdmarkdown7.5 KB
references/progress-indicator-as-scrubber.mdmarkdown6.0 KB
references/responsive-gate-size-not-platform.mdmarkdown9.0 KB
references/scoped-composable-shadows-the-top-level-one.mdmarkdown5.3 KB
references/screen-shell-content-split.mdmarkdown7.2 KB
references/selection-mode-state-holder.mdmarkdown8.0 KB
references/self-hiding-child-cannot-hide-its-slot.mdmarkdown5.2 KB
references/settings-value-round-tripped-through-its-label.mdmarkdown6.2 KB
references/stacked-bars-double-consume-window-insets.mdmarkdown8.7 KB
references/story-reel-auto-pager.mdmarkdown8.5 KB
references/swipe-action-list-row.mdmarkdown7.7 KB
references/type-safe-nav-graph-organization.mdmarkdown7.6 KB
references/variant-layout-math-stays-in-the-variant.mdmarkdown5.8 KB
references/weight-fill-false-to-center-a-cluster.mdmarkdown8.6 KB

references/progress-indicator-as-scrubber.md

View on GitHub
---
name: progress-indicator-as-scrubber
description: Build a seek control from a progress indicator plus a transparent pointer layer instead of from a slider — a hit box taller than the visual, drags consumed so an ancestor pager cannot steal a scrub, the drag's own fraction shown while interacting, a thumb drawn by you, and the separate decision of drawing an element closer without moving its layout slot. Use when the visual you need has no slider equivalent, when a scrub gets hijacked by a swipe or a sheet, when the bar jumps back mid-drag, or when a thin control is impossible to hit.
---

# A scrubber made from a progress indicator

Two layers in one box: the indicator draws, and a transparent gesture layer over it maps positions to
a fraction. You own the hit area, the arbitration and the thumb — which is the whole reason to do it
this way.

Reach for `custom-thin-media-slider` instead when the platform slider can render what you want and
you only need custom track and thumb slots; it keeps the accessibility semantics and the keyboard
handling for free. Come here when the visual has no slider counterpart, or when you need a hit area
and a consumption policy the slider does not expose — and then accept that semantics are now yours to
add.

## Traps

**The hit area is a separate size from the visual, and it is the one thing a slider will not give
you.** A few-pixels-tall line is unhittable. Put the indicator inside a box with a comfortable height
(40dp here), centre it, and hang the gestures on the box:

```kotlin
// adapted
Box(contentAlignment = Alignment.CenterStart, modifier = modifier.fillMaxWidth().height(40.dp)
        .onSizeChanged { widthPx = it.width }
        .pointerInput(Unit) { detectTapGestures { … } }
        .pointerInput(Unit) { detectHorizontalDragGestures(…) }) { Indicator(…); Thumb(…) }
```

**Consume the drag, every event, or an ancestor steals the scrub in progress.** A horizontal pager or
a draggable sheet above this control will claim the gesture the moment its own threshold is crossed,
and the scrub stops halfway with the page sliding away. `change.consume()` inside `onHorizontalDrag`
is what prevents it.

**While interacting, the drag's fraction wins over the incoming position.** The player keeps
publishing positions during the scrub; if the bar renders those, it visibly fights the finger. One
line settles it:

```kotlin
// as written
val displayedFraction = (if (isInteracting) dragFraction else progressFraction).coerceIn(0f, 1f)
```

The same gate is why `isInteracting` must be cleared in `onDragCancel` as well as `onDragEnd` — a
cancelled gesture that leaves the flag set freezes the bar on the last drag value forever.

**Tap and drag are two `pointerInput` blocks, not one.** A tap is not a zero-length drag, and the two
detectors in a single block have to arbitrate by hand. Separate blocks let the tap commit
immediately — set the fraction, emit, and emit the finished callback in the same breath — while the
drag path holds `isInteracting` for its duration.

**Guard the width.** `onSizeChanged` has not fired on the first frames, so every fraction computed
from it divides by zero: `if (widthPx <= 0) 0f else (x / widthPx).coerceIn(0f, 1f)`.

**Subtract the thumb's own width when placing it**, or the thumb overhangs the right edge at the end
of the track: `x = ((widthPx - thumbWidthPx) * displayedFraction)`. Compute it inside the
`offset { }` lambda so a morphing thumb re-places itself without recomposing the caller.

**Decoration must vanish at zero.** A wave, glow or ripple drawn on an empty track reads as progress
that is not there — gate it on the drawn fraction (`if (p > 0f) amplitude else 0f`), and see
`dont-pre-animate-a-self-animating-property` for why that amplitude must be a raw target rather than
a tween.

**Drawing something closer is not the same decision as moving it.** The time row under the bar sat
too far from the wave and too close to the transport row. `Modifier.offset(y = (-8).dp)` shifts what
is *painted*: the row keeps its layout slot, so the 8dp it gives up above reappears below, and — the
part that matters — the scrubber's 40dp touch target is untouched. Reaching for padding or a smaller
height instead trades a visual nudge for a smaller hit area, which is the bug this control exists to
avoid. The rule generalises: if the fix is about appearance only, use a draw-time modifier and leave
measurement alone.

**Convert scales once, at the boundary.** Internally everything is a 0..1 fraction; the callback
emits whatever the rest of the app already speaks (here a 0..100 percent). Doing that arithmetic in
more than one place is how a bar ends up permanently full or permanently empty.

**You have opted out of the slider's semantics.** Nothing here is focusable, announces a value, or
responds to a keyboard. If the surface needs any of that, add `Modifier.semantics` with a progress
value and a `setProgress` action explicitly — the cost is real, and it is the argument for
`custom-thin-media-slider` where a slider would have done.

## Verifying it

1. Every horizontal drag detector, paired with its consume call — a detector with no `change.consume()`
   under it is a scrub waiting to be stolen:

   ```bash
   grep -rn --include='*.kt' --exclude-dir=build -A18 "detectHorizontalDragGestures(" . \
     | grep -E "detectHorizontalDragGestures\(|change.consume\(\)"
   ```

2. Both interaction-end paths clear the flag. `onDragEnd` and `onDragCancel` must both appear:

   ```bash
   grep -rn --include='*.kt' --exclude-dir=build "onDragEnd = \|onDragCancel = " .
   ```

3. Draw-time nudges, each of which should be a deliberate appearance-only decision:

   ```bash
   grep -rn --include='*.kt' --exclude-dir=build -A2 "\.offset(y = " .
   ```

4. By hand, in this order: tap near the right edge (thumb lands under the finger, not past the end);
   drag slowly and stop mid-track while audio keeps playing (the bar must not jump); start a drag on
   the bar and continue horizontally well past it (the page behind must not move); start a drag and
   let go outside the window (the bar must resume following the player).
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall