Scope for the children of Grid.

Summary

Constants
const Int

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 Int

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

Public functions
Modifier
Modifier.gridItem(rows: IntRange, columns: IntRange, alignment: Alignment)

Configures the position, span, and alignment of an element within a Grid layout using ranges.
Cmn
Modifier
Modifier.gridItem(
    row: Int,
    column: Int,
    rowSpan: Int,
    columnSpan: Int,
    alignment: Alignment
)

Configures the position, span, and alignment of an element within a Grid layout.
Cmn

Constants

GridIndexUnspecified

Cmn 
@ExperimentalGridApi
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 
@ExperimentalGridApi
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.

Public functions

gridItem

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

Configures the position, span, and alignment of an element within a Grid layout using ranges.

This convenience overload converts IntRange 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: IntRange

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: IntRange

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: Alignment = Alignment.TopStart

Specifies how the content should be aligned within the grid cell(s). Defaults to Alignment.TopStart.
See also
gridItem

gridItem

Cmn 
fun Modifier.gridItem(
    row: Int = GridIndexUnspecified,
    column: Int = GridIndexUnspecified,
    rowSpan: Int = 1,
    columnSpan: Int = 1,
    alignment: Alignment = Alignment.TopStart
): Modifier

Configures the position, span, and alignment of an element within a Grid layout.

Apply this modifier to direct children of a Grid 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 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 row or column are left to their default value (GridIndexUnspecified), the Grid layout will automatically place the item based on the configured GridFlow.

Parameters
row: Int = 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 [-MaxGridIndex, MaxGridIndex]. Defaults to GridIndexUnspecified for auto-placement.
column: Int = 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 [-MaxGridIndex, MaxGridIndex]. Defaults to GridIndexUnspecified for auto-placement.
rowSpan: Int = 1

The number of rows this item should occupy. Must be greater than 0. Defaults to 1.
columnSpan: Int = 1

The number of columns this item should occupy. Must be greater than 0. Defaults to 1.
alignment: Alignment = Alignment.TopStart

Specifies how the content should be aligned within the grid cell(s) it occupies. Defaults to Alignment.TopStart.
Throws
kotlin.IllegalArgumentException

if row or column (when specified) are outside the valid range, or if rowSpan or columnSpan are less than 1.
See also
GridIndexUnspecified
MaxGridIndex