Skip to content

feat: add PlaceholderTransitions presets for fade animations#1

Open
rainxchzed wants to merge 2 commits intoRevenueCat:mainfrom
rainxchzed:animation-presets
Open

feat: add PlaceholderTransitions presets for fade animations#1
rainxchzed wants to merge 2 commits intoRevenueCat:mainfrom
rainxchzed:animation-presets

Conversation

@rainxchzed
Copy link

🎯 Goal

Introduce PlaceholderTransitions to simplify placeholder fade-in/fade-out animations with convenient presets.

Currently, developers must manually create animation specs for transitions:

placeholderFadeTransitionSpec = { spring(stiffness = Spring.StiffnessLow) }

This PR adds discoverable presets:

placeholderFadeTransitionSpec = PlaceholderTransitions.smooth

Why this matters: Makes the API more accessible for common use cases while maintaining full customization for advanced needs.

🛠 Implementation Details

Changes:

  • Added PlaceholderTransitions object with 6 presets: fast, normal, smooth, slow, snappy, bouncy
  • Added custom builders: custom() and tween() for fine-grained control
  • Comprehensive KDoc documentation explaining when to use each preset

Design decisions:

  1. Named PlaceholderTransitions (not AnimationDefaults) to clearly distinguish from PlaceholderDefaults (which provides highlight effects like shimmer/fade/pulse)
  2. Returns () -> FiniteAnimationSpec<Float> to match exact parameter signature
  3. Preset values based on Material Design motion guidelines
  4. 100% backward compatible - purely additive, no breaking changes

Key distinction:

  • PlaceholderDefaults = animated effects on the placeholder (shimmer, pulse, etc.)
  • PlaceholderTransitions = how placeholder appears/disappears

✍️ Examples

Basic usage:

Box(
  modifier = Modifier
    .placeholder(
      visible = isLoading,
      highlight = PlaceholderDefaults.shimmer,
      placeholderFadeTransitionSpec = PlaceholderTransitions.fast
    )
)

Different in/out transitions:

Text(
  text = "Loading...",
  modifier = Modifier.placeholder(
    visible = isLoading,
    placeholderFadeTransitionSpec = PlaceholderTransitions.slow,   // Slow fade in
    contentFadeTransitionSpec = PlaceholderTransitions.snappy      // Quick reveal
  )
)

Custom timing:

Image(
  painter = painter,
  contentDescription = null,
  modifier = Modifier.placeholder(
    visible = isLoading,
    placeholderFadeTransitionSpec = PlaceholderTransitions.tween(300)
  )
)

Available presets:

  • fast - 200ms tween for quick loading
  • normal - Default spring for balanced motion
  • smooth - Low stiffness spring for elegant transitions
  • slow - 800ms tween for deliberate loading
  • snappy - High stiffness spring for instant feel
  • bouncy - Low damping spring for playful effect

Demo video:
Screen_recording_20251015_064300.webm

✅ Prepare for Review

./gradlew spotlessApply  # ✅ Completed
./gradlew apiDump        # ✅ Completed

API changes:

  • Added new public object: PlaceholderTransitions
  • No modifications to existing API
  • Binary compatibility maintained

@rainxchzed rainxchzed requested a review from skydoves as a code owner October 15, 2025 01:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant