gridlayout-compose
2.7.4indexedOffers simple, non-lazy grid layout composables for streamlined UI design, mirroring the API of lazy grids but without requiring size or position calculations.
138
Stars
—
Used by
dependents
72
Health
/ 100
GridLayout for Compose
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:
Features
Installation
To download this library, add dependency to your gradle:
dependencies {
implementation("com.cheonjaeung.compose.grid:grid:<version>")
}
If you want to download before 2.0.0, use following:
dependencies {
implementation("io.woong.compose.grid:grid:<version>")
}
Getting Started
Box 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.
Item(modifier = Modifier.column(2))
}
Sequential Grid
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.
Performance
Benchmarks measure first-composition cost across three grid implementations.
[!NOTE] Measured on Galaxy S23 (SM-S911N), Android 16, CPU locked at 3.36 GHz.
The measured library version is 2.7.2
First Composition Time (Median)
Allocation Count (Median)
- VerticalGrid ≈ RowColumn: No performance overhead over manually written
Row+Columncode, meaning the simpler API comes for free. - VerticalGrid is faster than LazyVerticalGrid: 20 ~ 40% faster on first composition for fully-visible grids, meaning this library is more efficient than LazyGrid for simple grids.
- VerticalGrid allocates less than LazyVerticalGrid: 2 ~ 4 times fewer allocations than LazyVerticalGrid, meaning lower GC pressure in allocation-sensitive scenarios.
[!NOTE] This benchmark shows only the first composition cost. If the dataset is large,
LazyVerticalGridis the right choice.
Building
This project is kotlin multiplatform project. It's recommended to setup kotlin multiplatform developement environment.
Samples
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).
Testing
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.
Binary Compatibility
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.
Contributing
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.
Changelog
Please see changelog file.
License
Copyright 2023 Cheon Jaeung
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance the License.
You may obtain a copy of the License at
https:
Unless applicable law agreed to writing, software
distributed under the License distributed an BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express implied.
See the License the specific language governing permissions
limitations under the License.
GridLayout for Compose is licensed under Apache License 2.0. See license file for more details.