# GridScope

Artifact: [androidx.compose.foundation:foundation-layout](https://developer.android.com/jetpack/androidx/releases/compose-foundation) [View Source](https://cs.android.com/search?q=file:androidx/compose/foundation/layout/Grid.kt+class:androidx.compose.foundation.layout.GridScope) Added in [1.11.0](https://developer.android.com/jetpack/androidx/releases/compose-foundation#1.11.0) Common/AllAndroid/JVM
- Cmn

  ```
  @LayoutScopeMarker
  interface GridScope
  ```

*** ** * ** ***

Scope for the children of `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/Grid.composable#Grid(kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Function1)`.

## Summary

| ### Constants |
|---|---|---|
| `const https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/GridScope#GridIndexUnspecified() = 0` Sentinel value indicating that a grid position (row or column) is not manually specified and should be determined automatically by the layout flow. | Cmn |
| `const https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/GridScope#MaxGridIndex() = 1000` The maximum allowed index for a row or column (inclusive). | Cmn |

| ### Public functions |
|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier.https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/GridScope#(androidx.compose.ui.Modifier).gridItem(kotlin.Any,androidx.compose.ui.Alignment)(areaId: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html, alignment: https://developer.android.com/reference/kotlin/androidx/compose/ui/Alignment)` Configures the position and alignment of an element within a `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/Grid.composable#Grid(kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Function1)` layout by referencing a named area. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier.https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/GridScope#(androidx.compose.ui.Modifier).gridItem(kotlin.ranges.IntRange,kotlin.ranges.IntRange,androidx.compose.ui.Alignment)(rows: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.ranges/-int-range/index.html, columns: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.ranges/-int-range/index.html, alignment: https://developer.android.com/reference/kotlin/androidx/compose/ui/Alignment)` Configures the position, span, and alignment of an element within a `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/Grid.composable#Grid(kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Function1)` layout using ranges. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier.https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/GridScope#(androidx.compose.ui.Modifier).gridItem(kotlin.Int,kotlin.Int,kotlin.Int,kotlin.Int,androidx.compose.ui.Alignment)( row: @https://developer.android.com/reference/kotlin/androidx/annotation/IntRange(from = -1000, to = 1000) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, column: @https://developer.android.com/reference/kotlin/androidx/annotation/IntRange(from = -1000, to = 1000) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, rowSpan: @https://developer.android.com/reference/kotlin/androidx/annotation/IntRange(from = 1) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, columnSpan: @https://developer.android.com/reference/kotlin/androidx/annotation/IntRange(from = 1) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, alignment: https://developer.android.com/reference/kotlin/androidx/compose/ui/Alignment )` Configures the position, span, and alignment of an element within a `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/Grid.composable#Grid(kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Function1)` layout. | Cmn |

## Constants

### GridIndexUnspecified

Cmn Added in [1.11.0](https://developer.android.com/jetpack/androidx/releases/compose-foundation#1.11.0)

```
const val GridIndexUnspecified = 0: Int
```

Sentinel value indicating that a grid position (row or column) is not manually specified and should be determined automatically by the layout flow.

### MaxGridIndex

Cmn Added in [1.11.0](https://developer.android.com/jetpack/androidx/releases/compose-foundation#1.11.0)

```
const val MaxGridIndex = 1000: Int
```

The maximum allowed index for a row or column (inclusive).

This hard limit prevents performance degradation, layout timeouts, or memory issues potentially caused by accidental loop overflows or unreasonably large sparse grid definitions.

**Note:** This value MUST NOT exceed `Short.MAX_VALUE` (32767). Named Area bounds are bit-packed into 16-bit segments, and larger values will silently truncate.

## Public functions

### Modifier.gridItem

Cmn Artifact: [androidx.compose.foundation:foundation-layout](https://developer.android.com/jetpack/androidx/releases/compose-foundation) [View Source](https://cs.android.com/search?q=file:androidx/compose/foundation/layout/Grid.kt+function:gridItem) Added in [1.12.0](https://developer.android.com/jetpack/androidx/releases/compose-foundation#1.12.0)

```
fun Modifier.gridItem(areaId: Any, alignment: Alignment = Alignment.TopStart): Modifier
```

Configures the position and alignment of an element within a `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/Grid.composable#Grid(kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Function1)` layout by referencing a named area.

Apply this modifier to direct children of a `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/Grid.composable#Grid(kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Function1)` composable. The `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/GridScope#(androidx.compose.ui.Modifier).gridItem(kotlin.Any,androidx.compose.ui.Alignment)` must correspond to an identifier defined using `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/GridConfigurationScope#area(kotlin.Any,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.Int)` within the `config` block of the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/Grid.composable#Grid(kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Function1)`.

**Multiple Items \& Overlapping:**

- **2D Areas:** If multiple items are assigned to the same fully specified 2D area (both row and column are fixed), they will stack on top of each other within those bounds. Z-ordering is determined by composition order (items declared later draw on top, mirroring `Box`).

- **1D Areas \& Flow:** If the referenced area is one-dimensional (e.g., it defines a row but leaves the column unspecified), placing multiple items into it triggers auto-flow. The items will automatically flow into the next available cells within that specific track.

**Fallback Behavior for Unknown Areas:** If the provided `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/GridScope#(androidx.compose.ui.Modifier).gridItem(kotlin.Any,androidx.compose.ui.Alignment)` identifier is not registered in the Grid configuration, this item will silently fall back to automatic placement to prevent runtime crashes.

```kotlin
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Grid
import androidx.compose.foundation.layout.columns
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.rows
import androidx.compose.material3.Text
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

Grid(
    modifier = Modifier.fillMaxSize().padding(16.dp),
    config = {
        // 1. Define Physical Tracks
        column(100.dp) // Sidebar track
        column(1.fr) // Main content track

        row(60.dp) // Header track
        row(1.fr) // Main content track
        row(50.dp) // Footer track

        gap(8.dp)

        // 2. Map Semantic Strings to physical coordinates
        area("header", row = 1, column = 1, columnSpan = 2)
        area("sidebar", row = 2, column = 1)
        area("content", row = 2, column = 2)
        area("footer", rows = 3..3, columns = 1..2)
    },
) {
    // 3. Place items purely by semantic intent!
    Box(
        modifier = Modifier.gridItem("header").background(Color.DarkGray).fillMaxSize(),
        contentAlignment = Alignment.Center,
    ) {
        Text("Header", color = Color.White)
    }

    Box(
        modifier = Modifier.gridItem("sidebar").background(Color.LightGray).fillMaxSize(),
        contentAlignment = Alignment.Center,
    ) {
        Text("Sidebar")
    }

    Box(
        modifier = Modifier.gridItem("content").background(Color.Cyan).fillMaxSize(),
        contentAlignment = Alignment.Center,
    ) {
        Text("Main Content")
    }

    Box(
        modifier = Modifier.gridItem("footer").background(Color.Gray).fillMaxSize(),
        contentAlignment = Alignment.Center,
    ) {
        Text("Footer", color = Color.White)
    }
}
```

```kotlin
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Grid
import androidx.compose.foundation.layout.columns
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.Text
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

Grid(
    modifier = Modifier.fillMaxSize().padding(16.dp),
    config = {
        // 1. Define physical tracks
        column(100.dp) // Sidebar track
        column(1.fr) // Main content track

        row(60.dp) // Header track
        row(1.fr) // Main content track

        gap(8.dp)

        // 2. Define 1-Dimensional Areas
        // 1D Area: Fix the row, leave column unspecified
        area("header", row = 1)

        // 1D Area: Fix the column, leave row unspecified
        area("sidebar", column = 1)

        // Fully specified 2D area
        area("content", row = 2, column = 2)
    },
) {
    // Because "header" is 1D, items automatically flow into available columns!
    // Logo takes the first available slot (row 1, col 1)
    Box(
        modifier = Modifier.gridItem("header").background(Color.Red).fillMaxSize(),
        contentAlignment = Alignment.Center,
    ) {
        Text("Logo", color = Color.White)
    }

    // Search automatically flows into the next available slot (row 1, col 2)
    Box(
        modifier = Modifier.gridItem("header").background(Color.Magenta).fillMaxSize(),
        contentAlignment = Alignment.Center,
    ) {
        Text("Search Bar", color = Color.White)
    }

    // Because "sidebar" is 1D (col=1), it flows into the next available row.
    // Since (row 1, col 1) is taken by Logo, this flows to (row 2, col 1).
    Box(
        modifier = Modifier.gridItem("sidebar").background(Color.Blue).fillMaxSize(),
        contentAlignment = Alignment.Center,
    ) {
        Text("Sidebar Menu", color = Color.White)
    }

    // Exact 2D placement
    Box(
        modifier = Modifier.gridItem("content").background(Color.Green).fillMaxSize(),
        contentAlignment = Alignment.Center,
    ) {
        Text("Main Content", color = Color.White)
    }
}
```

| Parameters |
|---|---|
| `areaId: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html` | The user-defined identifier corresponding to the area defined in the Grid configuration. This identifier **must** have a stable `equals()` and `hashCode()` implementation (e.g., an `enum`, `String`, `data class`, or singleton `object`) to correctly match the area registered in the configuration. |
| `alignment: https://developer.android.com/reference/kotlin/androidx/compose/ui/Alignment = Alignment.TopStart` | Specifies how the content should be aligned within the grid cell(s). Defaults to `https://developer.android.com/reference/kotlin/androidx/compose/ui/Alignment#TopStart()`. |

### Modifier.gridItem

Cmn Artifact: [androidx.compose.foundation:foundation-layout](https://developer.android.com/jetpack/androidx/releases/compose-foundation) [View Source](https://cs.android.com/search?q=file:androidx/compose/foundation/layout/Grid.kt+function:gridItem) Added in [1.11.0](https://developer.android.com/jetpack/androidx/releases/compose-foundation#1.11.0)

```
fun Modifier.gridItem(
    rows: IntRange,
    columns: IntRange,
    alignment: Alignment = Alignment.TopStart
): Modifier
```

Configures the position, span, and alignment of an element within a `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/Grid.composable#Grid(kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Function1)` layout using ranges.

This convenience overload converts `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.ranges/-int-range/index.html` inputs into row/column indices and spans.

**Equivalence:**

- `rows = 4..5` maps to `row = 4`, `rowSpan = 2`.

- `columns = 1..1` maps to `column = 1`, `columnSpan = 1`.

Example: `Modifier.gridItem(rows = 2..3, columns = 1..2)` is functionally equivalent to `Modifier.gridItem(row = 2, rowSpan = 2, column = 1, columnSpan = 2)`.

| Parameters |
|---|---|
| `rows: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.ranges/-int-range/index.html` | The range of rows to occupy (e.g., `1..2`). The start determines the row index, and the size of the range determines the span. |
| `columns: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.ranges/-int-range/index.html` | The range of columns to occupy (e.g., `1..3`). The start determines the column index, and the size of the range determines the span. |
| `alignment: https://developer.android.com/reference/kotlin/androidx/compose/ui/Alignment = Alignment.TopStart` | Specifies how the content should be aligned within the grid cell(s). Defaults to `https://developer.android.com/reference/kotlin/androidx/compose/ui/Alignment#TopStart()`. |

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/GridScope#(androidx.compose.ui.Modifier).gridItem(kotlin.Int,kotlin.Int,kotlin.Int,kotlin.Int,androidx.compose.ui.Alignment)` |   |

### Modifier.gridItem

Cmn Artifact: [androidx.compose.foundation:foundation-layout](https://developer.android.com/jetpack/androidx/releases/compose-foundation) [View Source](https://cs.android.com/search?q=file:androidx/compose/foundation/layout/Grid.kt+function:gridItem) Added in [1.11.0](https://developer.android.com/jetpack/androidx/releases/compose-foundation#1.11.0)

```
fun Modifier.gridItem(
    row: @IntRange(from = -1000, to = 1000) Int = GridIndexUnspecified,
    column: @IntRange(from = -1000, to = 1000) Int = GridIndexUnspecified,
    rowSpan: @IntRange(from = 1) Int = 1,
    columnSpan: @IntRange(from = 1) Int = 1,
    alignment: Alignment = Alignment.TopStart
): Modifier
```

Configures the position, span, and alignment of an element within a `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/Grid.composable#Grid(kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Function1)` layout.

Apply this modifier to direct children of a `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/Grid.composable#Grid(kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Function1)` composable.

**Default Behavior:** If this modifier is not applied to a child, the child will be automatically placed in the next available cell (spanning 1 row and 1 column) according to the configured `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/GridFlow`.

**Indexing:** Grid row and column indices are **1-based**.

- **Positive** values count from the start (1 is the first row/column).

- **Negative** values count from the end (-1 is the last explicitly defined row/column).

**Auto-placement:** If `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/GridScope#(androidx.compose.ui.Modifier).gridItem(kotlin.Int,kotlin.Int,kotlin.Int,kotlin.Int,androidx.compose.ui.Alignment)` or `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/GridScope#(androidx.compose.ui.Modifier).gridItem(kotlin.Int,kotlin.Int,kotlin.Int,kotlin.Int,androidx.compose.ui.Alignment)` are left to their default value (`https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/GridScope#GridIndexUnspecified()`), the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/Grid.composable#Grid(kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Function1)` layout will automatically place the item based on the configured `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/GridFlow`.

| Parameters |
|---|---|
| `row: @https://developer.android.com/reference/kotlin/androidx/annotation/IntRange(from = -1000, to = 1000) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html = GridIndexUnspecified` | The specific 1-based row index to place the item in. Positive values count from the start (1 is the first row). Negative values count from the end (-1 is the last row). Must be within the range \[-`https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/GridScope#MaxGridIndex()`, `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/GridScope#MaxGridIndex()`\]. Defaults to `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/GridScope#GridIndexUnspecified()` for auto-placement. |
| `column: @https://developer.android.com/reference/kotlin/androidx/annotation/IntRange(from = -1000, to = 1000) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html = GridIndexUnspecified` | The specific 1-based column index to place the item in. Positive values count from the start (1 is the first column). Negative values count from the end (-1 is the last column). Must be within the range \[-`https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/GridScope#MaxGridIndex()`, `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/GridScope#MaxGridIndex()`\]. Defaults to `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/GridScope#GridIndexUnspecified()` for auto-placement. |
| `rowSpan: @https://developer.android.com/reference/kotlin/androidx/annotation/IntRange(from = 1) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html = 1` | The number of rows this item should occupy. Must be greater than 0. Defaults to 1. |
| `columnSpan: @https://developer.android.com/reference/kotlin/androidx/annotation/IntRange(from = 1) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html = 1` | The number of columns this item should occupy. Must be greater than 0. Defaults to 1. |
| `alignment: https://developer.android.com/reference/kotlin/androidx/compose/ui/Alignment = Alignment.TopStart` | Specifies how the content should be aligned within the grid cell(s) it occupies. Defaults to `https://developer.android.com/reference/kotlin/androidx/compose/ui/Alignment#TopStart()`. |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html` | if `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/GridScope#(androidx.compose.ui.Modifier).gridItem(kotlin.Int,kotlin.Int,kotlin.Int,kotlin.Int,androidx.compose.ui.Alignment)` or `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/GridScope#(androidx.compose.ui.Modifier).gridItem(kotlin.Int,kotlin.Int,kotlin.Int,kotlin.Int,androidx.compose.ui.Alignment)` (when specified) are outside the valid range, or if `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/GridScope#(androidx.compose.ui.Modifier).gridItem(kotlin.Int,kotlin.Int,kotlin.Int,kotlin.Int,androidx.compose.ui.Alignment)` or `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/GridScope#(androidx.compose.ui.Modifier).gridItem(kotlin.Int,kotlin.Int,kotlin.Int,kotlin.Int,androidx.compose.ui.Alignment)` are less than 1. |

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/GridScope#GridIndexUnspecified()` |   |
| `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/GridScope#MaxGridIndex()` |   |