GridConfigurationScope

public interface GridConfigurationScope : Density

Scope for configuring the structure of a Grid.

This interface is implemented by the configuration block in Grid. It allows defining columns, rows, and gaps.

The order in which column and row functions are called within the config block is important. Tracks are added to the grid definition sequentially based on these calls. For example, calling column(100.dp) twice defines two columns.

Gap configuration calls (gap, rowGap, columnGap) follow a "last-call-wins" policy for their respective axes.

Properties

constraints

public val constraints: Constraints

The layout constraints passed to this Grid from its parent.

These constraints represent the minimum and maximum size limits that the parent has imposed on this Grid. This can be useful for creating responsive layouts that adapt based on available space.

flow

public var flow: GridFlow

The direction in which items that do not specify a position are placed. Defaults to GridFlow.Row.

fr

public val Int.fr: Fr

Creates an Fr unit from an Int.

fr

public val Float.fr: Fr

Creates an Fr unit from a Float.

fr

public val Double.fr: Fr

Creates an Fr unit from a Double.

Functions

column

public fun column(size: Dp)

Defines a fixed-width column. Maps to GridTrackSize.Fixed.

column

public fun column(weight: Fr)

Defines a flexible column. Maps to GridTrackSize.Flex.

column

public fun column(@FloatRange(from = 0.0, to = 1.0) percentage: Float)

Defines a percentage-based column. Maps to GridTrackSize.Percentage.

Parameters

column

public fun column(size: GridTrackSize)

Defines a new column track with the specified size.

row

public fun row(size: Dp)

Defines a fixed-width row. Maps to GridTrackSize.Fixed.

row

public fun row(weight: Fr)

Defines a flexible row. Maps to GridTrackSize.Flex.

row

public fun row(@FloatRange(from = 0.0, to = 1.0) percentage: Float)

Defines a percentage-based row. Maps to GridTrackSize.Percentage.

Parameters

row

public fun row(size: GridTrackSize)

Defines a new row track with the specified size.

area

public fun area(
        areaId: Any,
        row: Int = GridIndexUnspecified,
        column: Int = GridIndexUnspecified,
        rowSpan: Int = 1,
        columnSpan: Int = 1,
    )

Defines a named area or a 1-dimensional track within the grid by mapping an identifier to physical starting coordinates and spans.

Once defined, this identifier can be referenced by child composables using Modifier.gridItem(areaId) to place them into this specific area. This decouples a component's semantic intent from its exact physical layout coordinates.

1D Areas & Flow: To create a 1-dimensional track, explicitly pass GridIndexUnspecified to the dimension you want to auto-flow. For example, area("Header", row = 1, column = GridIndexUnspecified) restricts the area to the first row, allowing multiple items placed into it to automatically flow side-by-side into available columns.

Parameters

Throws: IllegalArgumentException

if both row and column are GridIndexUnspecified.

area

public fun area(areaId: Any, rows: IntRange, columns: IntRange)

Defines a named area within the grid using explicit coordinate ranges.

This is a convenience overload that computes the starting coordinate and span based on the provided IntRange boundaries.

Example: area(AppArea.Footer, rows = 2..3, columns = 1..2) is functionally equivalent to area(AppArea.Footer, row = 2, column = 1, rowSpan = 2, columnSpan = 2).

Parameters

gap

public fun gap(all: Dp)

Sets both the row and column gaps (gutters) to all.

Precedence: If this is called multiple times, or mixed with columnGap or rowGap, the last call takes precedence.

Throws: IllegalArgumentException

if all is negative.

gap

public fun gap(row: Dp, column: Dp)

Sets independent gaps for rows and columns.

Precedence: If this is called multiple times, or mixed with columnGap or rowGap, the last call takes precedence.

Throws: IllegalArgumentException

if row or column is negative.

columnGap

public fun columnGap(gap: Dp)

Sets the gap (gutter) size between columns.

Precedence: If this is called multiple times, the last call takes precedence. This call will overwrite the column component of any previous gap call.

Throws: IllegalArgumentException

if gap is negative.

rowGap

public fun rowGap(gap: Dp)

Sets the gap (gutter) size between rows.

Precedence: If this is called multiple times, the last call takes precedence. This call will overwrite the row component of any previous gap call.

Throws: IllegalArgumentException

if gap is negative.

minmax

@Stable public fun minmax(min: Dp, max: Fr): GridTrackSize

A flexible track with an explicitly defined minimum base size and a flexible maximum size. Conceptually, this behaves identically to the CSS Grid minmax(min, max) function.

Usage with Lazy Lists: Because minmax relies on a predefined min size (e.g., 0.dp), it entirely bypasses the intrinsic measurement pass. This makes it the required choice when placing SubcomposeLayout-backed components (such as LazyColumn or LazyRow) inside a flexible grid track.

Parameters