Awesome

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.

Mosaic Grid Demo

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
Xcode 14 or higher

Installation

CocoaPods

You can easily install MosaicGrid via CocoaPods. Add the following line to your Podfile:

pod 'MosaicGrid', '~> 1.2.0'

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: https://github.com/hainayanda/MosaicGrid.git
Choose Up to Next Major for the version rule and set the version to 1.2.0.
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:

dependencies: [
    .package(url: "https://github.com/hainayanda/MosaicGrid.git", .upToNextMajor(from: "1.2.0"))
]

Then, include it in your target:

 .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.

Grid Anatomy

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:

Photos App Freestyle

VMosaicGrid

Vertical Mosaic

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.

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:

Vertical Mosaic Arrangement

You can customize how the grid size is calculated by using these 3 different init:

public init(hGridCount: Int, spacing: MosaicGridSpacing = .zero, gridAspectRatio: Double = 1, @ViewBuilder content: @escaping () -> Content) { ... }

public init(hGridCount: Int, spacing: MosaicGridSpacing = .zero, gridHeight: CGFloat, @ViewBuilder content: @escaping () -> Content) { ... }

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:

 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

Horizontal Mosaic

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.

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:

Horizontal Mosaic Arrangement

You can customize how the grid size is calculated by using these 3 different init:

 public init(vGridCount: Int, spacing: MosaicGridSpacing = .zero, gridAspectRatio: Double = 1, @ViewBuilder content: @escaping () -> Content) { ... }

 public init(vGridCount: Int, spacing: MosaicGridSpacing = .zero, gridWidth: CGFloat, @ViewBuilder content: @escaping () -> Content) { ... }

 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:

 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.

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.

// Using Integer literal
VMosaicGrid(hGridCount: 3, spacing: 2) { ... }

// Using Double literal
VMosaicGrid(hGridCount: 3, spacing: 2.0) { ... }

// 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 file.

License

MosaicGrid is available under the MIT license. See the LICENSE file for more info.

Credits

This project is maintained by Nayanda Haberty.