WaterfallGrid

WaterfallGrid is a versatile grid layout designed specifically for SwiftUI, providing a unique and flexible way to present content in an irregular grid format. This layout adapts beautifully to different device orientations, offering a seamless user experience that is both aesthetic and functional.

Features

WaterfallGrid boasts an array of impressive features designed to enhance the flexibility and presentation of content:

Irregular Grid Layout: Content is laid out in a non-uniform grid, providing a dynamic and modern aesthetic.
Responsive Design: The number of columns adjusts based on the device orientation, making it adaptable to both portrait and landscape views.
Customizable Spacing and Padding: Users can easily modify the spacing between items and the padding around the grid.
Flexible Scroll Directions: Supports both horizontal and vertical scrolling to fit various design needs.
Animated Updates: Changes to content within the grid can be smoothly animated, enhancing the user experience.

Usage

Initialization

Creating a WaterfallGrid is straightforward. Developers can transform any collection of data into a grid of views using a closure that supplies a view for each element. It works seamlessly with identifiable data, much like SwiftUI.List.

Example Usage

Image Grid by Key Path: Display a series of images using data identifiable by a key path.

WaterfallGrid((0..<10), id: \.self) { index in
  Image("image\(index)")
    .resizable()
    .aspectRatio(contentMode: .fit)
}

Identifiable Data Grid: Render a collection of custom views from identifiable data.

WaterfallGrid(rectangles) { rectangle in
  RectangleView(rectangle: rectangle)
}

Alternatively, for straightforward cases:

WaterfallGrid(rectangles, content: RectangleView.init)

Grid Style Customization

Columns Configuration: Adjust the number of columns to suit different orientations.

WaterfallGrid(cards, content: CardView.init)
.gridStyle(
  columnsInPortrait: 2,
  columnsInLandscape: 3
)

Spacing and Padding: Set the distance between items and the margins around the grid.

WaterfallGrid(rectangles, content: RectangleView.init)
.gridStyle(spacing: 8)
.padding(EdgeInsets(top: 16, leading: 8, bottom: 16, trailing: 8))

Animation Effects: Add smooth transitions for content updates.

WaterfallGrid(rectangles, content: RectangleView.init)
.gridStyle(animation: .easeInOut(duration: 0.5))

Scroll Behavior

Embedding in ScrollView: Include the grid in a scrollable view with optional indicators.

ScrollView(showsIndicators: true) {
  WaterfallGrid(rectangles, content: RectangleView.init)
}

Horizontal Scrolling: Enable horizontal scrolling for a different browsing experience.

ScrollView(.horizontal) {
  WaterfallGrid(rectangles, content: RectangleView.init)
  .scrollOptions(direction: .horizontal)
}

A Complete Example

Here's a full example demonstrating various features:

ScrollView(.horizontal, showsIndicators: false) {
  WaterfallGrid(cards) { card in
    CardView(card: card)
  }
  .gridStyle(
    columnsInPortrait: 2,
    columnsInLandscape: 3,
    spacing: 8,
    animation: .easeInOut(duration: 0.5)
  )
  .scrollOptions(direction: .horizontal)
  .padding(EdgeInsets(top: 16, leading: 8, bottom: 16, trailing: 8))
}

Sample Application

For those wanting to explore WaterfallGrid's capabilities, the WaterfallGridSample app provides detailed demonstrations through interactive examples.

Installation

Swift Package Manager

To integrate WaterfallGrid into an app, users can use the Swift Package Manager by adding a dependency via the Xcode interface or directly through Package.swift.

dependencies: [
  .package(url: "https://github.com/paololeonardi/WaterfallGrid.git", from: "1.1.0")
]

CocoaPods

Installation is also possible through CocoaPods by including the following in the Podfile:

pod 'WaterfallGrid', '~> 1.1.0'

Then run the pod install to complete the integration.

Conclusion

WaterfallGrid offers developers a flexible, easy-to-use tool for creating grids within SwiftUI applications, adapting gracefully to different use cases and interfaces. With its customizable features and support, it simplifies the process of building organized, visually appealing layouts.