@LayoutScopeMarker
@ExperimentalGridApi
interface GridConfigurationScope : DensityScope 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
val constraints: ConstraintsThe 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
var flow: GridFlowThe direction in which items that do not specify a position are placed. Defaults to GridFlow.Row.
fr
@ExperimentalGridApi
val Int.fr: FrCreates an Fr unit from an Int.
fr
@ExperimentalGridApi
val Float.fr: FrCreates an Fr unit from a Float.
fr
@ExperimentalGridApi
val Double.fr: FrCreates an Fr unit from a Double.
Functions
column
fun column(size: Dp)Defines a fixed-width column. Maps to GridTrackSize.Fixed.
column
fun column(weight: Fr)Defines a flexible column. Maps to GridTrackSize.Flex.
column
fun column(@FloatRange(from = 0.0, to = 1.0) percentage: Float)Defines a percentage-based column. Maps to GridTrackSize.Percentage.
Parameters
| percentage | The percentage (0.0 to 1.0) of the available space. |
column
fun column(size: GridTrackSize)Defines a new column track with the specified size.
row
fun row(size: Dp)Defines a fixed-width row. Maps to GridTrackSize.Fixed.
row
fun row(weight: Fr)Defines a flexible row. Maps to GridTrackSize.Flex.
row
fun row(@FloatRange(from = 0.0, to = 1.0) percentage: Float)Defines a percentage-based row. Maps to GridTrackSize.Percentage.
Parameters
| percentage | The percentage (0.0 to 1.0) of the available space. |
row
fun row(size: GridTrackSize)Defines a new row track with the specified size.
area
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
| areaId | A user-defined identifier (e.g., an Enum, String, or object marker) that represents this area. This identifier must have a stable equals() and hashCode(). |
| row | The 1-based starting row index of the area. Defaults to GridIndexUnspecified to create a 1D column-based area where items flow vertically. |
| column | The 1-based starting column index of the area. Defaults to GridIndexUnspecified to create a 1D row-based area where items flow horizontally. |
| rowSpan | The number of rows this area should occupy. Must be greater than 0. Defaults to 1. |
| columnSpan | The number of columns this area should occupy. Must be greater than 0. Defaults to 1. |
area
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.
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
| areaId | A user-defined identifier (e.g., an Enum, String, or object marker) that represents this area. |
| rows | The range of rows to occupy (e.g., 1..2). The start determines the 1-based 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 1-based column index, and the size of the range determines the span. |
gap
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.
gap
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.
columnGap
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.
rowGap
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.
minmax
fun minmax(min: Dp, max: Fr): GridTrackSizeA 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
| min | The explicit minimum fixed base size (e.g., 0.dp). |
| max | The maximum flexible distribution weight (e.g., 1.fr). |
