ComposeParallaxToolbar - Compose Multiplatform

A fully customizable Material 3 parallax toolbar layout built with Compose Multiplatform. This cross-platform library provides a modern, material design parallax effect for app bars that animate smoothly as users scroll through content, working seamlessly on Android, iOS.

Features

• Material 3 Integration: Built with Material 3 components, theming, and color system
• Highly Customizable: Full control over colors, dimensions, animations, and behaviors
• Parallax Effect: Smooth transitions and animations while scrolling
• Title & Subtitle: Animated title and subtitle with customizable transitions
• Curved Motion: Beautiful quadratic Bézier curve animations for title transitions
• Cross-Platform: Full support for Android, iOS with native integration

Installation

Compose Multiplatform Projects

For Compose Multiplatform projects, add the dependency to your shared module's build.gradle.kts:

kotlin {
    sourceSets {
        commonMain {
            dependencies {
                implementation("am.highapps.parallaxtoolbar:compose-parallax-toolbar-kmp:1.1.0")
            }
        }
    }
}

This will make the library available in all your platform-specific source sets (androidMain, iosMain, etc.).

Android Only Projects

Gradle (Kotlin DSL)

Add the dependency to your module's build.gradle.kts file:

dependencies {
    implementation("am.highapps.parallaxtoolbar:compose-parallax-toolbar-kmp:1.1.0")
}

Gradle (Groovy)

dependencies {
    implementation 'am.highapps.parallaxtoolbar:compose-parallax-toolbar-kmp:1.1.0'
}

iOS Installation

Direct XCFramework Integration

For direct integration:

1. Download the project from GitHub repository

2. After downloading, run the following command to build the iOS framework:

./gradlew buildIosFramework

3. Create XCFramework by running:

xcodebuild -create-xcframework \
-framework compose-parallax-toolbar-kmp/build/bin/iosArm64/releaseFramework/compose_parallax_toolbar_kmp.framework \
-framework compose-parallax-toolbar-kmp/build/bin/iosSimulatorArm64/releaseFramework/compose_parallax_toolbar_kmp.framework \
-output compose-parallax-toolbar-kmp.xcframework

4. Integrate XCFramework with Xcode:

   • Open ios folder in Xcode
   • Add the XCFramework to ios project:
     • Go to Targets → Project → General → Frameworks, Libraries, and Embedded Content
     • Click + → Add Other → Add Files
     • Navigate to generated compose-parallax-toolbar-kmp.xcframework and add it

5. Import in your Swift files:

import compose_parallax_toolbar_kmp

Basic Usage

Here's a simple example of how to implement the parallax toolbar in your Compose code:

import am.highapps.parallaxtoolbar.ComposeParallaxToolbarLayout

@Composable
fun MyScreen() {
    ComposeParallaxToolbarLayout(
        titleContent = { isCollapsed ->
            Text(
                text = "My App",
                style = if (isCollapsed)
                    MaterialTheme.typography.titleMedium
                else
                    MaterialTheme.typography.headlineMedium
            )
        },
        headerContent = {
            // Your header image or content
            Image(
                painter = painterResource(id = R.drawable.header),
                contentDescription = null,
                contentScale = ContentScale.Crop,
                modifier = Modifier.fillMaxSize()
            )
        },
        content = { _ ->
            // Your main content
            Column(modifier = Modifier.padding(16.dp)) {
                repeat(10) {
                    Card(
                        modifier = Modifier
                            .fillMaxWidth()
                            .padding(vertical = 8.dp)
                    ) {
                        Text(
                            text = "Item $it",
                            modifier = Modifier.padding(16.dp)
                        )
                    }
                }
            }
        }
    )
}

Platform Integration

Android Integration

For Android, you can use the component directly in your Compose UI:

@Composable
fun AndroidScreen() {
    // Use Material Theme from your Android app
    MaterialTheme {
        ComposeParallaxToolbarLayout(
            // Component parameters as shown in Basic Usage
            // ...
        )
    }
}

iOS Integration

UIKit Integration

import UIKit
import compose_parallax_toolbar_kmp

class MyViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()
        
        let composeVC = IosParallaxToolbarSampleKt.CustomParallaxToolbarViewController()
        addChild(composeVC)
        view.addSubview(composeVC.view)
        composeVC.view.frame = view.bounds
        composeVC.didMove(toParent: self)
    }
}

SwiftUI Integration

import SwiftUI
import compose_parallax_toolbar_kmp

struct ComposeToolbarView: UIViewControllerRepresentable {
    func makeUIViewController(context: Context) -> UIViewController {
        return IosParallaxToolbarSampleKt.CustomParallaxToolbarViewController()
    }
    func updateUIViewController(_ uivc: UIViewController, context: Context) {}
}

struct ContentView: View {
    var body: some View {
        ComposeToolbarView()
            .ignoresSafeArea(edges: .top)  // Optional: makes the toolbar use full height
    }
}

iOS Sample View Controllers:

• SimpleParallaxToolbarViewController() - Basic implementation
• CustomParallaxToolbarViewController() - Implementation with custom styling
• MinimalParallaxToolbarViewController() - Minimalist implementation
• InitiallyCollapsedToolbarViewController() - Starts with collapsed toolbar

Custom Implementations

To create custom implementations, you need to add your custom composable functions in the common code (specifically in the iOS part of the multiplatform module), then use them from your iOS application.

Step 1: Add your custom implementation in the common code (iOS part):

// Add this in src/iosMain/kotlin (common code - iOS part)
fun MyCustomToolbarViewController() = ComposeUIViewController {
    MaterialTheme {
        ComposeParallaxToolbarLayout(
            titleContent = { isCollapsed ->
                Text(
                    text = "My Custom Title",
                    fontSize = if (isCollapsed) 18.sp else 24.sp,
                    fontWeight = FontWeight.Bold
                )
            },
            headerContent = {
                // Your header content
            },
            content = {
                // Your main content
            }
        )
    }
}

Step 2: After adding your custom implementation, rebuild the framework:

./gradlew buildIosFramework

Step 3: Use it in your iOS application:

// In your iOS app
let customVC = IosParallaxToolbarSampleKt.MyCustomToolbarViewController()

Note: Custom implementations cannot be created directly in the iOS application code. They must be added to the common multiplatform code (iOS part) and then accessed from the iOS app.

For more details:

• iOS Integration Guide - Setup and basic usage
• iOS Sample Implementation Guide - Detailed examples

Advanced Customization

For more control, use the ParallaxToolbarDefaults object to customize various aspects:

// Create customized configurations using factory methods
val headerConfig = ParallaxToolbarDefaults.headerConfig(
    height = 400.dp,
    gradient = Brush.verticalGradient(
        colors = listOf(
            Color.Transparent,
            Color(0x80000000),
            Color(0xCC000000)
        ),
        startY = 300f
    )
)

val titleConfig = ParallaxToolbarDefaults.titleConfig(
    paddingStart = 20.dp,
    collapsedPaddingStart = 60.dp,
    keepSubtitleAfterCollapse = true,
    animateSubTitleHiding = true
)

val toolbarConfig = ParallaxToolbarDefaults.toolbarConfig(
    initialColor = Color.Transparent,
    targetColor = MaterialTheme.colorScheme.surface,
    elevation = 2.dp,
    animationSpec = tween(durationMillis = 400)
)

val bodyConfig = ParallaxToolbarDefaults.bodyConfig(
    minBottomSpacerHeight = 32.dp
)

ComposeParallaxToolbarLayout(
    // Required parameters
    titleContent = { /* ... */ },
    headerContent = { /* ... */ },
    content = { /* ... */ },
    
    // Optional customizations
    headerConfig = headerConfig,
    toolbarConfig = toolbarConfig,
    titleConfig = titleConfig,
    bodyConfig = bodyConfig
)

Documentation

For detailed information on all components, parameters, and configuration options, see the API Documentation.

Compatibility

• Kotlin: 2.1.21
• Compose Multiplatform: 1.8.2
• Android: API 24+ (Android 7.0+)
• iOS: iOS 14+

Best Practices

Material 3 Integration

• Use Material 3 typography and color schemes
• Adapt your UI using the isCollapsed parameter
• Leverage Material 3 components like TopAppBar

Performance Optimization

• Avoid heavy computations in recomposing content
• Use remember and derivedStateOf for scroll-based calculations
• Optimize images for mobile rendering

Multiplatform Considerations

• Use platform-agnostic libraries for image loading
• Handle differences in status bar behavior
• Test across screen sizes for responsive layouts

Troubleshooting

Common Issues

Android

• Ensure you're using a compatible Material 3 theme
• Use proper insets handling to avoid system UI overlaps

iOS

• "No such module" errors: check framework linkage
• Memory issues: maintain strong references to view controllers

Changelog

Version 1.1.0

• Updated to Kotlin 2.1.20
• Updated to Compose Multiplatform 1.8.1
• Ios integration details update

Version 1.0.0

• Initial release
• Basic parallax toolbar functionality
• Material 3 support

Contribution

Contributions are welcome! Check out the Contributing Guidelines for more information.

Acknowledgments

This library was inspired by and based mainly on the excellent article Collapsing toolbar with parallax effect and curve motion in Jetpack Compose by Morad Azzouzi.

Author & Support

This project was created by Hayk Arustamyan.

⭐ If you find this library helpful, consider giving it a star on GitHub!

If this project helps you reduce time to develop, you can give me a cup of coffee :)

License

MIT License

Copyright (c) 2025 Hayk Arustamyan

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.