ConstraintLayout 🗜️📏

ConstraintLayout is a layout manager for Android which allows you to position and size widgets in a flexible way. It's available for both the Android view system and Jetpack Compose.

This repository contains the core Java engine, Android library, validation tools, and experiments.

Android Reference Docs

Have a question that isn't answered here? Try StackOverflow for ConstraintLayout or MotionLayout.

Using ConstraintLayout

⬇️ Installation

Add the Gradle dependency:

You need to make sure you have the Google repository included in the build.gradle file in the root of your project:

repositories {
    google()
}

Next add a dependency in the build.gradle file of your Gradle module.

If using ConstraintLayout with the Android View system, add:

dependencies {

    implementation("androidx.constraintlayout:constraintlayout:2.1.3")

}

If using ConstraintLayout with Jetpack Compose, add:

dependencies {

    implementation("androidx.constraintlayout:constraintlayout-compose:1.0.0")

}

Additionally, for MotionLayout with Jetpack Compose, you require to opt-in to ExprimentalMotionApi:

tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach {
    kotlinOptions {
        // For Kotlin 1.6.0+
        freeCompilerArgs += "-opt-in=androidx.constraintlayout.compose.ExperimentalMotionApi"
        
        // For older than Kotlin 1.6.0
        freeCompilerArgs += "-Xopt-in=androidx.constraintlayout.compose.ExperimentalMotionApi"
    }
}

🎒🥾 Requirements

AndroidX (Your gradle.properties must include android.useAndroidX=true)
Min SDK 14+
Java 8+

✨🤩📱 Key Features

Hello World

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    >

    <TextView
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Hello World!"
        app:layout_constraintTop_toTopOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintBottom_toBottomOf="parent" />

</androidx.constraintlayout.widget.ConstraintLayout>

📐 Aspect Ratio defines one dimension of a widget as a ratio of the other one. If both width and height are set to 0dp the system sets the largest dimensions that satisfy all constraints while maintaining the aspect ratio.

<ImageView
    android:id="@+id/image_1"
    android:layout_width="0dp"
    android:layout_height="0dp"
    app:layout_constraintDimensionRatio="1:1"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintTop_toTopOf="parent"
    app:layout_constraintBottom_toBottomOf="parent"
    tools:src="@tools:sample/avatars" />

⛓️ Chains provide group-like behavior in a single axis (horizontally or vertically). The other axis can be constrained independently.

🦮 Guidelines allow reactive layout behavior with fixed or percentage based positioning for multiple widgets.

<androidx.constraintlayout.widget.Guideline
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:id="@+id/guideline"
    app:layout_constraintGuide_begin="100dp"
    android:orientation="vertical"/>

🚧 Barrier references multiple widgets to create a virtual guideline based on the most extreme widget on the specified side.

<androidx.constraintlayout.widget.Barrier
    android:id="@+id/barrier"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    app:barrierDirection="start"
    app:constraint_referenced_ids="button1,button2" />

☂️ Group controls the visibility of a set of referenced widgets.

<androidx.constraintlayout.widget.Group
    android:id="@+id/group"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:visibility="visible"
    app:constraint_referenced_ids="button4,button9" />

💫 MotionLayout a subclass of ConstraintLayout that supports transitions between constraint sets defined in MotionScenes. See projects/MotionLayoutExperiments for examples.

🌊 Flow is a VirtualLayout that allows positioning of referenced widgets horizontally or vertically similar to a Chain. If the referenced elements do not fit within the given bounds it has the ability to wrap them and create multiple chains. See projects/CalculatorExperiments for examples.

🌀 CircularFlow is a VirtualLayout that easily organize objects in a circular pattern. See projects/CarouselExperiments for basic examples and projects/MotionLayoutVerification for examples with MotionLayout.

<androidx.constraintlayout.helper.widget.CircularFlow
   android:id="@+id/circularFlow"
   android:layout_width="match_parent"
   android:layout_height="match_parent"
   app:circularflow_angles="0,40,80,120"
   app:circularflow_radiusInDP="90,100,110,120"
   app:circularflow_viewCenter="@+id/view1"
   app:constraint_referenced_ids="view2,view3,view4,view5" />

📚👩‍🏫 Learning Materials

Build a Responsive UI with ConstraintLayout
ConstraintLayout Codelab
Introduction to MotionLayout Part I | Part II | Part III | Part IV
MotionLayout Codelab

🤝 Contributing

If you'd like to get involved and contribute please read CONTRIBUTING for details on our code of conduct, and the process for submitting pull requests to us.

💻 Authors

John Hoford : MotionLayout (jafu888)
Nicolas Roard : ConstraintLayout (camaelon)

See also the list of contributors who participated in this project.

🔖 License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details

AndroidGecko/constraintlayout