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:version")
            }
        }
    }
}

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:version")
}

Gradle (Groovy)

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

iOS Installation Options

There are several ways to integrate the library in your iOS project:

Option 1: Swift Package Manager (Recommended)

Integrate the published Maven Central artifact via SPM:

1. In Xcode: File → Add Package Dependencies...
2. Enter the repository URL: https://github.com/haykarustamyan/ComposeParallaxToolbar
3. Select the version rules you want to follow
4. Click "Add Package"

Option 2: CocoaPods

Use the published Maven Central artifact via CocoaPods:

pod 'compose_parallax_toolbar_kmp', 'version'

Option 3: Manual Integration

For direct integration without package managers:

1. Download the XCFramework from the releases page
2. Drag the XCFramework into your Xcode project
3. Ensure it's added to "Frameworks, Libraries, and Embedded Content" with "Embed & Sign" option

Option 4: Build from Source

For custom modifications or using the latest code, follow the instructions in the iOS Integration Guide to build the framework from source.

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

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: 1.9.0+
• Compose Multiplatform: 1.5.0+
• Android: API 21+ (Android 5.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.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.