Skip to content

About

A Compose Multiplatform library with polished UI components, settings and DataStore infrastructure, and resource utilities.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

18 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

m3-extended

Maven Central Version

An extended Material 3 Expressive design system for Compose Multiplatform. M3X coordinates appearance and interaction through shared design contracts, with reusable infrastructure for application UI. Its resource and AndroidX DataStore layers can also be used independently of Material UI.

Getting Started

Add the components you need to your build.gradle.kts file. For the complete Material composition and M3X theme with Capsule shapes:

dependencies {
    implementation("top.ltfan.m3x:material-bundle:<version>")
}

In a Kotlin Multiplatform module, put these dependency declarations in the source set that uses M3X, such as commonMain.dependencies.

Or if you are using Gradle Version Catalogs, add the following to your gradle/libs.versions.toml:

[versions]
m3x = "<version>"

[libraries]
m3x-material-bundle = { module = "top.ltfan.m3x:material-bundle", version.ref = "m3x" }

Then use the catalog aliases in the same dependency scope:

dependencies {
    implementation(libs.m3x.material.bundle)
}

Make sure your settings.gradle.kts includes the repositories used by M3X and its dependencies:

dependencyResolutionManagement {
    repositories {
        mavenCentral()
        google()
    }
}

Wrap application UI in M3xMaterialTheme when using the optional theme:

import top.ltfan.m3x.material.bundle.M3xMaterialTheme

@Composable
fun App() {
    M3xMaterialTheme {
        // Application content
    }
}

Choose other library modules from the module table, using top.ltfan.m3x:<module>:<version>. The settings and DataStore processors require the additional KSP configuration described in the settings and persistence guides.

Documentation

Start with the documentation guide. The design-system contracts specify theme composition, shape and material roles, accessibility, motion, and component behavior individually, with source and regression links.

Modules

Module Responsibility
runtime Integration with Compose Runtime.
ui, ui-platform-private UI infrastructure and separately selected private platform integration.
animation-core, animation Low-level animation foundations and Compose UI animation support.
foundation Unstyled Compose UI foundations.
navigation-event Integration with NavigationEvent.
material3 Integration with upstream Compose Material 3.
overlay Design-independent overlay infrastructure.
backdrop, overlay-backdrop Backdrop integration for Compose UI and overlay infrastructure.
material-theme, material M3X theme contracts and Material 3 Expressive components.
material-overlay, material-backdrop Material overlay components and Backdrop integration.
material-theming, material-theming-capsule Theme integration and optional Capsule integration.
material-bundle Integrated M3X design system.
resource-core, resource-compose UI-independent resource abstractions and Compose integration.
settings-page-core, settings-page-compose, settings-page-material Settings contracts and optional Compose and Material integration.
settings-page-datastore DataStore integration for settings.
datastore-core, datastore-compose, datastore-serialization DataStore persistence foundations and optional Compose and serialization integration.
datastore-processor, settings-page-processor, processor-support Code generation and shared processor infrastructure.
compose-test-support Shared Compose test infrastructure.
demo Shared demo application.
demo-android, demo-desktop, demo-web, demo-macos, demo-ios Platform integration for the shared demo.

Module boundaries follow abstraction and dependency direction. The guides describe concrete API contracts within those boundaries; their examples do not define a module's full scope.

Theme integration

The Material UI is designed and tested for MaterialExpressiveTheme and reads the caller's theme. For the adaptive Capsule preset and coordinated M3X theme, explicitly add top.ltfan.m3x:material-bundle and wrap the UI in M3xMaterialTheme. Choose material-theming with M3xBaseTheme when using the independent base theme, and add material-theming-capsule explicitly when selecting its continuous shape factory. See theme composition for inheritance and scoped customization.

Backdrop page setup

Backdrop needs a page source that the glass surfaces can sample. Create one handle for the page, provide it outside OverlayHost, and capture only the page background and ordinary content. Place glass components outside that capture node so they do not sample themselves. OverlayHost then captures and links any number of overlays in their drawing order; the caller does not build the overlay layer stack.

Inside an existing MaterialTheme, a page can use this template (with the usual Compose and M3X imports):

@Composable
fun ExampleBackdropPage() {
    var selected by remember { mutableIntStateOf(0) }
    var dialogOpen by remember { mutableStateOf(false) }
    val pageLayer = rememberBackdropLayer()
    val overlayState = remember { OverlayHostState() }

    ProvideM3xMaterialRendering {
        BackdropHost(pageLayer) {
            OverlayHost(overlayState) {
                Box(Modifier.fillMaxSize()) {
                    Box(
                        Modifier
                            .fillMaxSize()
                            .captureBackdrop(pageLayer)
                            .background(MaterialTheme.colorScheme.background),
                    ) {
                        Button(onClick = { dialogOpen = true }) { Text("Open dialog") }
                    }

                    FloatingBottomBar(
                        selectedTabIndex = selected,
                        onTabSelected = { selected = it },
                        modifier = Modifier.align(Alignment.BottomCenter),
                    ) {
                        item { Text("Home") }
                        item { Text("Settings") }
                    }

                    OverlayDialog(
                        onDismissRequest = { dialogOpen = false },
                        visible = { dialogOpen },
                        containerColor = MaterialTheme.colorScheme.surface,
                    ) {
                        Text("Dialog content")
                    }
                }
            }
        }
    }
}

The captureBackdrop modifier precedes background so the background is inside the captured draw subtree. Additional page capture layers can be built with the lower-level backdrop APIs when a page needs more than one source.

See backdrop integration for source boundaries, fallback, and local sampling; overlay integration specifies host requirements and dismissal behavior.

Demo application

Run the desktop application with ./gradlew :demo-desktop:run. Build the Android launcher with ./gradlew :demo-android:assembleDebug (Android API 24 or later); :demo-android:assembleOptimized produces the R8- and resource-shrunk APK with debug signing. Package the desktop launchers with ./gradlew :demo-desktop:packageReleaseArtifacts and the native macOS launcher with ./gradlew :demo-macos:packageReleaseArtifacts. Web launchers are :demo-web:jsBrowserDevelopmentRun and :demo-web:wasmJsBrowserDevelopmentRun; :demo-web:pagesDistribution builds the Wasm site deployed to GitHub Pages. Run the experimental macOS Native application with ./gradlew :demo-macos:runDebugExecutableMacosArm64. Open demo-ios/iosApp/M3xDemo.xcodeproj and run the shared M3xDemo scheme on a simulator or device supported by its deployment target. The target uses Kotlin's direct framework integration and supports iPad multiple windows. Device builds require a Development Team; simulator builds do not need signing. See demo packaging for CI artifact names, outputs, and packaging JDK requirements.

The demo includes component and overlay catalogs, a Backdrop Lab, and settings examples. Architecture explains their state boundaries; development covers build and packaging details.

About

A Compose Multiplatform library with polished UI components, settings and DataStore infrastructure, and resource utilities.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages