DOCSEARCHbyAlgolia
Submit Docs

compose-shimmer

repository·master·Indexed 21 days ago

https://github.com/valentinilk/compose-shimmer

A library providing shimmering animation effects for Jetpack Compose and Compose Multiplatform (CMP). It features a .shimmer() modifier, customizable ShimmerTheme via CompositionLocal, and various ShimmerBounds strategies (View, Window, and Custom) to manage animation velocity and synchronization across different layout types.

Tokens
1.6K
Snippets
6
Records
7
Agent score
27%

What's inside compose-shimmer

  1. Understand modifier placement for shimmer

    master

    The order of modifiers is critical. The shimmer() modifier affects only the elements that follow it in the modifier chain.

    1. Shimmering background: If .shimmer() is placed before .background(), the background itself will shimmer.
    2. Non-shimmering background: If .shimmer() is placed after .background(), the background will remain static, and only the content/subsequent modifiers will shimmer.
    // The background WILL shimmer
Box(
    modifier = Modifier
        .size(128.dp)
        .shimmer()
        .background(Color.Blue)
)

// The background WILL NOT shimmer
Box(
    modifier = Modifier
        .size(128.dp)
        .background(Color.Blue)
        .shimmer()
)

  2. How ShimmerBounds work

    master

    By default, each shimmer() modifier calculates its own animation velocity based on the view's size. To synchronize animations or handle specific layouts (like scrollable lists), use rememberShimmer with different ShimmerBounds strategies:

    • ShimmerBounds.View (default): Uses the specific view's height and width as boundaries. Each view has its own animation velocity.
    • ShimmerBounds.Window: Uses the window's coordinate system. The shimmer travels across the entire window, but only affects views with the shimmer() modifier. Note: This may look odd in scrollable content as the shimmer position is relative to the window, not the content.
    • ShimmerBounds.Custom: The shimmer is not drawn until you manually call updateBounds(position) on the returned Shimmer instance. This is ideal for scrollable lists where you want the shimmer to move with the content.
    // Example: Using ShimmerBounds.Custom for scrollable content
val shimmerInstance = rememberShimmer(ShimmerBounds.Custom)
Column(
    modifier = Modifier
        .fillMaxSize()
        .verticalScroll(rememberScrollState())
        .onGloballyPositioned { layoutCoordinates ->
            // Use the library's unclippedBoundsInWindow() extension
            val position = layoutCoordinates.unclippedBoundsInWindow()
            shimmerInstance.updateBounds(position)
        },
) {
    Text("Shimmering Text", modifier = Modifier.shimmer(shimmerInstance))
}

  3. Quick Start: Apply the shimmer modifier

    master

    To create a shimmering effect, apply the .shimmer() modifier to a UI component. Every UI element defined after the shimmer() modifier in the modifier chain will be affected by the animation.

    @Composable
fun ShimmeringPlaceholder() {
    Row(
        modifier = Modifier
            .shimmer() // <- Affects all subsequent UI elements
            .fillMaxWidth()
            .padding(16.dp),
        horizontalArrangement = Arrangement.spacedBy(16.dp),
    ) {
        Box(
            modifier = Modifier
                .size(80.dp, 80.dp)
                .background(Color.LightGray),
        )
        // ... other components
    }
}

  4. Run the sample applications

    master

    The repository includes sample apps for various platforms. To run them, clone the repository and use the following methods:

    • Android: Open in Android Studio and run the sample configuration.
    • iOS: Open the iosApp folder in Xcode, configure signing, and run on an emulator/device.
    • Desktop: Run the sample.desktop configuration in Android Studio or use ./gradlew :sample:run.
    • Browser: Run the sample.browser configuration in Android Studio or use ./gradlew :sample:jsBrowserDevelopmentRun.
    • WebAssembly (Wasm): Run the sample.wasm configuration in Android Studio or use ./gradlew :sample:wasmJsBrowserDevelopmentRun.

  5. Install compose-shimmer via Maven Central

    master

    Add the following dependency to your build.gradle(.kts) file to use the library in your project. Ensure you are using a version compatible with your Compose version.

    Shimmer VersionBased on Compose
    1.5.01.11
    1.4.01.10.3
    1.3.31.8.1
    1.3.21.7.3
    dependencies {
    implementation("com.valentinilk.shimmer:compose-shimmer:1.5.0")
}

  6. Configure ShimmerTheme using CompositionLocal

    master

    The library provides ShimmerTheme to customize properties like rotation or width. You can provide a global theme using CompositionLocalProvider with LocalShimmerTheme. It is recommended to integrate this into your custom MaterialTheme.

    val yourShimmerTheme = defaultShimmerTheme.copy(/* Set your desirable values */)

CompositionLocalProvider(
    LocalShimmerTheme provides yourShimmerTheme
) {
    /* content */
}

  7. Initialize a Shimmer instance with rememberShimmer

    master

    Use the rememberShimmer composable function to create and manage a Shimmer instance within a Composable scope. This function handles the lifecycle of the shimmer effect, theme, and bounds. It requires a ShimmerBounds object to define the area where the shimmer effect is applied.

    val shimmer = rememberShimmer(
    shimmerBounds = ShimmerBounds.View(), // Or ShimmerBounds.Window(), ShimmerBounds.Custom(rect)
)
    val shimmer = rememberShimmer(
    shimmerBounds = ShimmerBounds.View()
)