ConstraintLayout is a layout that allows you to place composables relative to other composables on the screen. It is an alternative to using multiple nested Row, Column, Box and other custom layout elements. ConstraintLayout is useful when implementing larger layouts with more complicated alignment requirements.

Consider using ConstraintLayout in the following scenarios:

• To avoid nesting multiple Columns and Rows for positioning elements on screen to improve readability of code.
• To position composables relative to other composables or to position composables based on guidelines, barriers or chains. In the View system, ConstraintLayout was the recommended way to create large and complex layouts, as a flat view hierarchy was better for performance than nested views are. However, this is not a concern in Compose, which is able to efficiently handle deep layout hierarchies.

The androidx.constraintlayout:constraintlayout-compose library is available for Jetpack Compose, but it is not currently available for Compose Multiplatform. This library changes that, by providing the ConstraintLayout for many of the platforms supported by Compose Multiplatform.

Usage is very simple:

import androidx.constraintlayout.compose.ConstraintLayout

@Composable
fun ConstraintLayoutContent() {
    ConstraintLayout {
        // Create references for the composables to constrain
        val (button, text) = createRefs()

        Button(
            onClick = { /* Do something */ },
            // Assign reference "button" to the Button composable
            // and constrain it to the top of the ConstraintLayout
            modifier = Modifier.constrainAs(button) {
                top.linkTo(parent.top, margin = 16.dp)
            }
        ) {
            Text("Button")
        }

        // Assign reference "text" to the Text composable
        // and constrain it to the bottom of the Button composable
        Text(
            "Text",
            Modifier.constrainAs(text) {
                top.linkTo(button.bottom, margin = 16.dp)
            }
        )
    }
}

You'll note that I have kept the package name the same as that in AndroidX. This is to enable easy migration for when support is added to Compose Multiplatform.

val commonMain by getting {
    dependencies {
        /// Compose 1.11.0+
        implementation("tech.annexflow.compose:constraintlayout-compose-multiplatform:0.8.1")
    }
}

If the androidx.constraintlayout package names clash with something else on your classpath — most often the real androidx.constraintlayout:constraintlayout-compose on Android — pick a relocated flavour instead. All three are built from the same sources and released under the same version.

/// Everything relocated — the flavour to reach for when you hit a clash
implementation("tech.annexflow.compose:constraintlayout-compose-multiplatform-shaded:0.8.1")

Two caveats:

• -shaded-compose relocates only the Compose layer and still ships the solver as androidx.constraintlayout.core, so it does not resolve a clash with androidx.constraintlayout:constraintlayout-core. Use -shaded for that.
• The flavours declare overlapping package names, so exactly one of them belongs on a classpath.

Before 0.8.0 the flavours were published as version suffixes on a single artifact. They are separate artifacts now, because a shared artifact id let Gradle's version-conflict resolution silently swap one flavour for another: 0.8.0-shaded becomes -shaded:0.8.0, and 0.8.0-shaded-core — which despite its name relocated the Compose layer, not the solver — becomes -shaded-compose:0.8.0.

Thanks to Chris Banes for the initial structure of the project.

Copyright 2026 The Android Open Source Project
Portions 2026 Sergei Gagarin
 
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.