# ConstraintSet

Artifact: [androidx.constraintlayout:constraintlayout-compose](https://developer.android.com/jetpack/androidx/releases/constraintlayout) [View Source](https://cs.android.com/search?q=file:androidx/constraintlayout/compose/ConstraintSet.kt+class:androidx.constraintlayout.compose.ConstraintSet) Added in [1.1.2](https://developer.android.com/jetpack/androidx/releases/constraintlayout#1.1.2)


```
interface ConstraintSet
```

<br />

*** ** * ** ***

Immutable description of the constraints used to layout the children of a `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstraintLayout.composable#ConstraintLayout(androidx.compose.ui.Modifier,kotlin.Int,androidx.compose.animation.core.AnimationSpec,kotlin.Function0,kotlin.Function1)`.

Layout items are defined with `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstraintSetScope#createRefFor(kotlin.Any)`, each layout item must be defined with a unique ID from other items in the same scope:

```kotlin
val textRef = createRefFor("text")
val imageRef = createRefFor("image")
```

You may also use `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstraintSetScope#createRefsFor(kotlin.Array)` to declare up to 16 items at a time using the destructuring declaration pattern:

```kotlin
val (textRef, imageRef) = createRefsFor("text", "image")
```

Individual constraints are defined with `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstraintLayoutBaseScope#constrain(androidx.constraintlayout.compose.HorizontalChainReference,kotlin.Function1)`. Where you can tell each layout reference how to constrain to other references including the **`parent`**:

```kotlin
constrain(textRef) {
    centerTo(parent)
}
constrain(imageRef) {
    centerVerticallyTo(textRef)
    start.linkTo(textRef.end, margin = 8.dp)
}
```

Here, we constrain the *textRef* to the center of the *parent* , while the image is centered vertically to *textRef* and is horizontally placed to the right of its end anchor with a margin (keep in mind, when using `center...`, `start` or `end` the layout direction will automatically change in RTL locales).

See `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstrainScope` to learn more about how to constrain elements together.

In the ConstraintLayout or MotionLayout Composables, the children must be bound using `https://developer.android.com/reference/kotlin/androidx/compose/ui/layout/layoutId.modifier#(androidx.compose.ui.Modifier).layoutId(kotlin.Any)`.

So, the whole snippet with ConstraintLayout would look like this:

```kotlin
val textId = "text"
val imageId = "image"
ConstraintLayout(
    constraintSet = ConstraintSet {
        val (textRef, imageRef) = createRefsFor(textId, imageId)
        constrain(textRef) {
            centerTo(parent)
        }
        constrain(imageRef) {
            centerVerticallyTo(textRef)
            start.linkTo(textRef.end, margin = 8.dp)
        }
    },
    modifier = Modifier.fillMaxSize()
) {
    Text(
        modifier = Modifier.layoutId(textId),
        text = "Hello, World!"
    )
    Image(
        modifier = Modifier.layoutId(imageId),
        imageVector = Icons.Default.Android,
        contentDescription = null
    )
}
```

## Helpers

You may also use helpers, a set of virtual (not shown on screen) components that provide special layout behaviors, you may find these in the `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstraintSetScope` with the '`create...`' prefix, a few of these are **Guidelines** , **Chains** and **Barriers**.

### Guidelines

Lines to which other `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstrainedLayoutReference`s may be constrained to, these are defined at either a fixed or percent position from an anchor of the ConstraintLayout parent (top, bottom, start, end, absoluteLeft, absoluteRight).

Example:

```kotlin
val (textRef) = createRefsFor(textId)
val vG = createGuidelineFromStart(fraction = 0.3f)

constrain(textRef) {
    centerVerticallyTo(parent)
    centerAround(vG)
}
```

See

- `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstraintLayoutBaseScope#createGuidelineFromTop(androidx.compose.ui.unit.Dp)`

- `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstraintLayoutBaseScope#createGuidelineFromBottom(androidx.compose.ui.unit.Dp)`

- `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstraintLayoutBaseScope#createGuidelineFromStart(androidx.compose.ui.unit.Dp)`

- `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstraintLayoutBaseScope#createGuidelineFromEnd(androidx.compose.ui.unit.Dp)`

- `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstraintLayoutBaseScope#createGuidelineFromAbsoluteLeft(androidx.compose.ui.unit.Dp)`

- `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstraintLayoutBaseScope#createGuidelineFromAbsoluteRight(androidx.compose.ui.unit.Dp)`

### Chains

Chains may be either horizontal or vertical, these, take a set of `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstrainedLayoutReference`s and create bi-directional constraints on each of them at the same orientation of the chain in the given order, meaning that an horizontal chain will create constraints between the start and end anchors.

The result, a layout that evenly distributes the space within its elements.

For example, to make a layout with three text elements distributed so that the spacing between them (and around them) is equal:

```kotlin
val (textRef0, textRef1, textRef2) = createRefsFor("text0", "text1", "text2")
createHorizontalChain(textRef0, textRef1, textRef2, chainStyle = ChainStyle.Spread)
```

You may set margins within elements in a chain with `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstraintLayoutBaseScope#(androidx.constraintlayout.compose.LayoutReference).withChainParams(androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,kotlin.Float)`:

```kotlin
val (textRef0, textRef1, textRef2) = createRefsFor("text0", "text1", "text2")
createHorizontalChain(
    textRef0,
    textRef1.withChainParams(startMargin = 100.dp, endMargin = 100.dp),
    textRef2,
    chainStyle = ChainStyle.Spread
)
```

You can also change the way space is distributed, as chains have three different styles:

- `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ChainStyle#Spread()` Layouts are evenly distributed after margins are accounted for (the space around and between each item is even). This is the **default** style for chains.

- `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ChainStyle#SpreadInside()` The first and last layouts are affixed to each end of the chain, and the rest of the items are evenly distributed (after margins are accounted for). I.e.: Items are spread from the inside, distributing the space between them with no space around the first and last items.

- `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ChainStyle#Packed(kotlin.Float)` The layouts are packed together after margins are accounted for, by default, they're packed together at the middle, you can change this behavior with the **bias** parameter of `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ChainStyle#Packed(kotlin.Float)`.

- Alternatively, you can make every Layout in the chain to be `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/Dimension#fillToConstraints()` and then set a particular weight to each of them to create a **weighted chain**.

#### Weighted Chain

Weighted chains are useful when you want the size of the elements to depend on the remaining size of the chain. As opposed to just distributing the space around and/or in-between the items.

For example, to create a layout with three text elements in a row where each element takes the exact same size regardless of content, you can use a simple weighted chain where each item has the same weight:

```kotlin
val (textRef0, textRef1, textRef2) = createRefsFor("text0", "text1", "text2")
createHorizontalChain(
    textRef0.withChainParams(weight = 1f),
    textRef1.withChainParams(weight = 1f),
    textRef2.withChainParams(weight = 1f),
    chainStyle = ChainStyle.Spread
)

constrain(textRef0, textRef1, textRef2) {
    width = Dimension.fillToConstraints
}
```

This way, the texts will horizontally occupy the same space even if one of them is significantly larger than the others.

Also note that when using `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstraintSetScope` you can apply the same constrains to multiple references at a time.

Keep in mind that chains have a relatively high performance cost. For example, if you plan on having multiple chains one below the other, consider instead, applying just one chain and using it as a reference to constrain all other elements to the ones that match their position in that one chain. It may provide increased performance with no significant changes in the layout output.

Alternatively, consider if other helpers such as `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstraintLayoutBaseScope#createGrid(kotlin.Array,kotlin.Int,kotlin.Int,kotlin.Boolean,androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,kotlin.FloatArray,kotlin.FloatArray,kotlin.Array,kotlin.Array,androidx.constraintlayout.compose.GridFlag)` can accomplish the same layout.

See

- `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstraintLayoutBaseScope#createHorizontalChain(kotlin.Array,androidx.constraintlayout.compose.ChainStyle)`

- `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstraintLayoutBaseScope#createVerticalChain(kotlin.Array,androidx.constraintlayout.compose.ChainStyle)`

- `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstraintLayoutBaseScope#(androidx.constraintlayout.compose.LayoutReference).withChainParams(androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,kotlin.Float)`

### Barriers

Barriers take a set of `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstrainedLayoutReference`s and creates the most further point in a given direction where other `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstrainedLayoutReference` can constrain to.

This is useful in situations where elements in a layout may have different sizes but you want to always constrain to the largest item, for example, if you have a text element on top of another and want an image to always be constrained to the end of them:

```kotlin
val (textRef0, textRef1, imageRef) = createRefsFor("text0", "text1", "image")

// Creates a point at the furthest end anchor from the elements in the barrier
val endTextsBarrier = createEndBarrier(textRef0, textRef1)

constrain(textRef0) {
    centerTo(parent)
}
constrain(textRef1) {
    top.linkTo(textRef0.bottom)
    start.linkTo(textRef0.start)
}

constrain(imageRef) {
    top.linkTo(textRef0.top)
    bottom.linkTo(textRef1.bottom)

    // Image will always be at the end of both texts, regardless of their size
    start.linkTo(endTextsBarrier, margin = 8.dp)
}
```

Be careful not to constrain a `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstrainedLayoutReference` to a barrier that references it or that depends on it indirectly. This creates a cyclic dependency that results in unsupported layout behavior.

See

- `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstraintLayoutBaseScope#createTopBarrier(kotlin.Array,androidx.compose.ui.unit.Dp)`

- `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstraintLayoutBaseScope#createBottomBarrier(kotlin.Array,androidx.compose.ui.unit.Dp)`

- `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstraintLayoutBaseScope#createStartBarrier(kotlin.Array,androidx.compose.ui.unit.Dp)`

- `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstraintLayoutBaseScope#createEndBarrier(kotlin.Array,androidx.compose.ui.unit.Dp)`

- `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstraintLayoutBaseScope#createAbsoluteLeftBarrier(kotlin.Array,androidx.compose.ui.unit.Dp)`

- `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstraintLayoutBaseScope#createAbsoluteRightBarrier(kotlin.Array,androidx.compose.ui.unit.Dp)`

## Summary

| ### Public functions |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstraintSet#applyTo(androidx.constraintlayout.compose.State,kotlin.collections.List)(state: https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/State, measurables: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/compose/ui/layout/Measurable>)` Applies the `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstraintSet` to a state. |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstraintSet#applyTo(androidx.constraintlayout.core.state.Transition,kotlin.Int)(transition: https://developer.android.com/reference/kotlin/androidx/constraintlayout/core/state/Transition, type: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)` |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstraintSet#isDirty(kotlin.collections.List)(measurables: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/compose/ui/layout/Measurable>)` |
| `open https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstraintSet` | `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstraintSet#override(kotlin.String,kotlin.Float)(name: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, value: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html)` |

## Public functions

### applyTo

```
fun applyTo(state: State, measurables: List<Measurable>): Unit
```

Applies the `https://developer.android.com/reference/kotlin/androidx/constraintlayout/compose/ConstraintSet` to a state.

### applyTo

Added in [1.1.2](https://developer.android.com/jetpack/androidx/releases/constraintlayout#1.1.2)

```
open fun applyTo(transition: Transition, type: Int): Unit
```

### isDirty

```
open fun isDirty(measurables: List<Measurable>): Boolean
```

### override

Added in [1.1.2](https://developer.android.com/jetpack/androidx/releases/constraintlayout#1.1.2)

```
open fun override(name: String, value: Float): ConstraintSet
```