🌈 Create new beautiful Compose Gradients with our new wesite ->
Interface

GridScope

Scope for the children of Grid.

Source set: Common
public interface GridScope

Scope for the children of Grid.

Functions

gridItem

Source set: Common
public fun Modifier.gridItem(
        row: Int = GridIndexUnspecified,
        column: Int = GridIndexUnspecified,
        @AndroidXIntRange(from = 1) rowSpan: Int = 1,
        @AndroidXIntRange(from = 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 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 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 The number of rows this item should occupy. Must be greater than 0. Defaults to 1.
columnSpan The number of columns this item should occupy. Must be greater than 0. Defaults to 1.
alignment Specifies how the content should be aligned within the grid cell(s) it occupies. Defaults to Alignment.TopStart.

Throws: IllegalArgumentException

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

gridItem

Source set: Common
public 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 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 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 Specifies how the content should be aligned within the grid cell(s). Defaults to Alignment.TopStart.

gridItem

Source set: Common
public fun Modifier.gridItem(areaId: Any, alignment: Alignment = Alignment.TopStart): Modifier

Configures the position and alignment of an element within a Grid layout by referencing a named area.

Apply this modifier to direct children of a Grid composable. The areaId must correspond to an identifier defined using GridConfigurationScope.area within the config block of the Grid.

Multiple Items & Overlapping:

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

  • 2D Areas: If multiple items are assigned to the same fully specified 2D area (both row

    • 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.

  • 1D Areas & Flow: If the referenced area is one-dimensional (e.g., it defines a row but

Fallback Behavior for Unknown Areas: If the provided areaId identifier is not registered in the Grid configuration, this item will silently fall back to automatic placement to prevent runtime crashes.

Parameters
areaId 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 Specifies how the content should be aligned within the grid cell(s). Defaults to Alignment.TopStart.

Members

Companion

Source set: Common
public companion object

Properties

MaxGridIndex

Source set: Common
@ExperimentalGridApi public const val MaxGridIndex: Int = 1000

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.

GridIndexUnspecified

Source set: Common
@ExperimentalGridApi public const val GridIndexUnspecified: Int = 0

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