https://github.com/hainayanda/mosaicgrid
MosaicGrid is a SwiftUI library that provides both horizontal and vertical mosaic grid views, along with utility functions for customizing view tile sizes and placement. These components allow you to arrange multiple items in a visually appealing grid layout.
https://github.com/hainayanda/mosaicgrid
grid mosaic swift swiftui
Last synced: 3 months ago
JSON representation
MosaicGrid is a SwiftUI library that provides both horizontal and vertical mosaic grid views, along with utility functions for customizing view tile sizes and placement. These components allow you to arrange multiple items in a visually appealing grid layout.
- Host: GitHub
- URL: https://github.com/hainayanda/mosaicgrid
- Owner: hainayanda
- License: mit
- Created: 2023-02-04T03:09:30.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-03-09T08:25:18.000Z (7 months ago)
- Last Synced: 2025-05-03T08:56:19.230Z (5 months ago)
- Topics: grid, mosaic, swift, swiftui
- Language: Swift
- Homepage:
- Size: 6.29 MB
- Stars: 25
- Watchers: 1
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# MosaicGrid
`MosaicGrid` is a SwiftUI library that provides both horizontal and vertical mosaic grid views, along with utility functions for customizing view tile sizes and placement. These components allow you to arrange multiple items in a visually appealing grid layout.
[](https://app.codacy.com/gh/hainayanda/MosaicGrid/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
[](https://swift.org/package-manager/)
[](https://cocoapods.org/pods/MosaicGrid)
[](https://cocoapods.org/pods/MosaicGrid)
[](https://cocoapods.org/pods/MosaicGrid)
## Example
To run the example project, clone the repo, and run `pod install` from the Example directory first.
## Requirements
- Swift 5.5 or higher
- iOS 16.0 or higher
- MacOS 13.0 or higher
- TVOS 16.0 or higher
- WatchOS 8.0 or higher
- VisionOS 1.0 or higher
- Xcode 14 or higher
## Installation
### CocoaPods
You can easily install MosaicGrid via [CocoaPods](https://cocoapods.org). Add the following line to your Podfile:
```ruby
pod 'MosaicGrid', '~> 2.0.2'
```
### Swift Package Manager (Xcode)
To install using Xcode's Swift Package Manager, follow these steps:
- Go to **File > Swift Package > Add Package Dependency**
- Enter the URL: ****
- Choose **Up to Next Major** for the version rule and set the version to **2.0.2**.
- Click "Next" and wait for the package to be fetched.
### Swift Package Manager (Package.swift)
If you prefer using Package.swift, add MosaicGrid as a dependency in your **Package.swift** file:
```swift
dependencies: [
.package(url: "https://github.com/hainayanda/MosaicGrid.git", .upToNextMajor(from: "2.0.2"))
]
```
Then, include it in your target:
```swift
.target(
name: "MyModule",
dependencies: ["MosaicGrid"]
)
```
## Usage
### Mosaic Grid Arrangement
`MosaicGrid` is similar to `UICollectionView`, but with much more flexibility. `MosaicGrid` will divide the view into grids (with spacing if have any) and allow you to utilize it for view placement.
How the placement will go will depend on the type of MosaicGrid you use, whether is it `VMosaicGrid` or `HMosaicGrid`. You can utilize `usingGrids(h:v:)` to control how many tiles will be used for each view. With this, arranging UI with grid placement will be very easy!
Like this photo album example, or this abstract-like art :stuck_out_tongue_winking_eye:
 
### VMosaicGrid
`VMosaicGrid` is a vertical mosaic grid view. It will try to fill the horizontal grids then continue down and make the view grow to the bottom.
```swift
VMosaicGrid(hGridCount: 3, spacing: 2) {
ForEach(models) { model in
MyView(from: model)
.usingGrids(h: model.width, v: model.height)
}
}
```
The arrangement will be following this pattern:
You can customize how the grid size is calculated by using these 3 different `init`:
```swift
public init(hGridCount: Int, spacing: MosaicGridSpacing = .zero, gridAspectRatio: Double = 1, @ViewBuilder content: @escaping () -> Content) { ... }
```
```swift
public init(hGridCount: Int, spacing: MosaicGridSpacing = .zero, gridHeight: CGFloat, @ViewBuilder content: @escaping () -> Content) { ... }
```
```swift
public init(gridSize: CGSize, minimumSpacing: MosaicGridSpacing = .zero, @ViewBuilder content: @escaping () -> Content) { ... }
```
If you don't want to specify the grid guide, you can use this init:
```swift
public init(spacing: MosaicGridSpacing = .zero, @ViewBuilder content: @escaping () -> Content) { ... }
```
But keep in mind that if you did not give any of `hGridCount` or `gridSize`, it will not calculate the grid guide, but it will place the view wherever it fit as compact as possible. `usingGrids(h:v:)` will not work too since there is no grid guide.
### HMosaicGrid
`HMosaicGrid` is a horizontal mosaic grid view. It will try to fill the vertical grids then continue right and make the view grow to the right.
```swift
HMosaicGrid(vGridCount: 3, spacing: 2) {
ForEach(models) { model in
MyView(from: model)
.usingGrids(h: model.width, v: model.height)
}
}
```
The arrangement will be following this pattern:
You can customize how the grid size is calculated by using these 3 different `init`:
```swift
public init(vGridCount: Int, spacing: MosaicGridSpacing = .zero, gridAspectRatio: Double = 1, @ViewBuilder content: @escaping () -> Content) { ... }
```
```swift
public init(vGridCount: Int, spacing: MosaicGridSpacing = .zero, gridWidth: CGFloat, @ViewBuilder content: @escaping () -> Content) { ... }
```
```swift
public init(gridSize: CGSize, minimumSpacing: MosaicGridSpacing = .zero, @ViewBuilder content: @escaping () -> Content) { ... }
```
If you don't want to specify the grid guide, you can use this init:
```swift
public init(spacing: MosaicGridSpacing = .zero, @ViewBuilder content: @escaping () -> Content) { ... }
```
But keep in mind that if you did not give any of `vGridCount` or `gridSize`, it will not calculate the grid guide, but it will place the view wherever it fit as compact as possible. `usingGrids(h:v:)` will not work too since there is no grid guide.
### SpacerTile
`SpacerTile` is a utility function to create a clear rectangle with a given tile size. It is used if you want to make sure some grids are not occupied with a view.
```swift
VMosaicGrid(hGridCount: 3, spacing: 2) {
ForEach(models) { model in
MyView(from: model)
.usingGrids(h: model.width, v: model.height)
// spacer that fills grid 3x1
SpacerTile(h: 3, v: 1)
}
}
```
Keep in mind that if you did not give any of `vGridCount`, `hGridCount`, or `gridSize`, SpacerTile will not work since there will be no grid guide.
### MosaicGridSpacing
`MosaicGridSpacing` is a struct representing horizontal and vertical spacing for Mosaic Grid. It's an object passed when creating MosaicGrid to represent spacing. Normally we can just use Double literal since this struct implements ExpressibleByFloatLiteral and ExpressibleByIntegerLiteral.
```swift
// Using Integer literal
VMosaicGrid(hGridCount: 3, spacing: 2) { ... }
```
```swift
// Using Double literal
VMosaicGrid(hGridCount: 3, spacing: 2.0) { ... }
```
```swift
// Using MosaicGridSpacing. h is horizontal spacing, v is vertical spacing
VMosaicGrid(hGridCount: 3, spacing: .init(h: 2, v: 2)) { ... }
```
## Contributing
Contributions are welcome! Please follow the guidelines in the [CONTRIBUTING.md](CONTRIBUTING.md) file.
## License
MosaicGrid is available under the MIT license. See the [LICENSE](LICENSE) file for more info.
## Credits
This project is maintained by [Nayanda Haberty](hainayanda@outlook.com).