GridLayout for Compose is a library that provides missing non-lazy grid layout composables for Compose Multiplatform.

Jetpack Compose doesn't offer non-lazy grid layouts, providing only lazy grids and alternatives (e.g., flow layouts). However, sometimes we need a simple grid layout for less complexity and more intuitive layout code. This library offers sequential grid, and box grid as simpler solutions for small grid UIs.

There are benefits of this library:

• Similar API to LazyGrid: The GridLayout's APIs are designed to provide similar development experience to LazyGrid.
• Easy to implement various grid: There are "Fixed", "Adaptive" and "FixedSize" for grid layout management like LazyGrid. Like LazyGrid, it eliminates dealing with different screen sizes.
• Simple to use as a part of LazyList: The GridLayout is not lazy layout. It can be simply placed in lazy layouts. If only a portion of the full layout is grid, No need to use LazyGrid with span size for full layout.
• Efficient for small datasets: LazyGrid has complex logics for large datasets. But when datasets are small, it can be inefficient. The GridLayout is just a simple layout. It can be more efficient for smaller datasets.
• Flexible item placement: This library provide BoxGrid layout to allow placing items at the specific row and column position.

• Non-Lazy Grid Layouts: Lightweight grid layouts optimized for small datasets, avoiding the overhead of lazy-loading logic.
  • Box Grid: Place items at specific row and column positions.
  • Sequential Grids: VerticalGrid and HorizontalGrid for simple sequential item placement.
  • Cell Management Support: Support for Fixed, Adaptive, and FixedSize cell management.
  • Spanning: Allow items to span across multiple rows or columns in both Box and Sequential grids.
  • RTL Support: Full support for Right-to-Left layout directions.

To download this library, add dependency to your gradle:

dependencies {
    implementation("com.cheonjaeung.compose.grid:grid:<version>")
}

After the 2.0.0 version, the group id and package name is changed from io.woong.compose.grid to com.cheonjaeung.compose.grid.

BoxGrid is a grid layout composable that allows you to place items in grid format. Items in BoxGrid can be placed in any position.

BoxGrid(
    modifier = Modifier.fillMaxSize(),
    rows = SimpleGridCells.Fixed(3),
    columns = SimpleGridCells.Fixed(3),
) {
    // It will be placed at 0, 0.
    Item()
    // It will be placed at 0, 1.
    Item(modifier = Modifier.row(1))
    // It will be placed at 1, 2.
    Item(modifier = Modifier.position(row = 2, column = 1))
    // It will be placed at 2, 0.
    Itme(modifier = Modifier.column(2))
}

VerticalGrid and HorizontalGrid are sequential grid layout composables. They place items sequentially in a grid format.

HorizontalGrid(
    rows = SimpleGridCells.Fixed(3),
    modifier = Modifier.fillMaxHeight()
) {
    Item() // It will be placed at 0, 0.
    Item() // It will be placed at 0, 1.
    Item() // It will be placed at 0, 2.
    Item() // It will be placed at 1, 0.
}

VerticalGrid(
    columns = SimpleGridCells.Fixed(3),
    modifier = Modifier.fillMaxWidth()
) {
    Item() // It will be placed at 0, 0.
    Item() // It will be placed at 1, 0.
    Item() // It will be placed at 2, 0.
    Item() // It will be placed at 0, 1.
}

For more information, please visit documentation site.

This project is kotlin multiplatform project. It's recommended to setup kotlin multiplatform developement environment.

This project contains sample app project in the samples directory. You can run sample app both Andorid and iOS (iOS sample app can run only on the macOS).

This project has unit tests and snapshot tests. Run following command to run all tests:

./gradlew :grid:test

To run only snapshot tests, run following command:

./gradlew :grid:verifyPaparazziDebug

If you add or edit snapshot tests, run following command to create new snapshots:

./gradlew :grid:recordPaparazziDebug

If test is failed, you can check what is wrong from diff images. The diff images are generated in grid/build/paparazzi/failures/ with delta-* name.

This project runs public binary API compatibility validation on CI. If you change public APIs, run following command before commit:

./gradlew apiDump

And you should commit api files with your code changes.

Welcome to contribute to this project! Feel free to create pull requests or issues.

• Patching: If you want to change code, make a pull request.
• Bug Reporting: If you think something is wrong, make an issue and add the bug label.
• Feature Requesting: If you want to request some features, make an issue and add the enhancement label.
• Questions: If you have some questions, make an issue and add the question label.

Please see changelog file.

Copyright 2023 Cheon Jaeung

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

GridLayout for Compose is licensed under Apache License 2.0. See license file for more details.