/constraintlayout

ConstraintLayout is an Android layout component which allows you to position and size widgets in a flexible way

Primary LanguageJavaApache License 2.0Apache-2.0

ConstraintLayout 🗜️📏

core GitHub license

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

Reference Docs for Compose

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.4")

}

If using ConstraintLayout with Jetpack Compose, add:

dependencies {

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

}

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

🤝 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