Parchment

Basic usage

Create a PageView instance with the pages you want to show. Each Page takes a title and a content view, which can be any SwiftUI view.

PageView {
    Page("Title 0") {
        Text("Page 0")
    }
    Page("Title 1") {
        Text("Page 1")
    }
}

By default, the menu items are displayed as titles, but you can also pass in any SwiftUI view as the menu item. The state parameter allows you to customize the menu item based on the selected state and scroll position of the view. For instance, you could show an icon that rotates based on its progress like this:

PageView {
    Page { state in
        Image(systemName: "star.fill")
            .rotationEffect(Angle(degrees: 90 * state.progress))
    } content: {
        Text("Page 1")
    }
}

Dynamic pages

To create a PageView with a dynamic number of pages, you can pass in a collection of items where each item is mapped to a Page:

PageView(items, id: \.self) { item in
    Page("Title \(item)") {
        Text("Page \(item)")
    }
}

Update selection

To select specific items, you can pass a binding into PageView with the index of the currently selected item. When updating the binding, Parchment will scroll to the new index.

@State var selectedIndex: Int = 0
...
PageView(selectedIndex: $selectedIndex) {
    Page("Title 1") {
        Button("Next") {
            selectedIndex = 1
        }
    }
    Page("Title 2") {
        Text("Page 2")
    }
}

Modifiers

You can customize the PageView using the following modifiers. See Options for more details on each option.

PageView {
    Page("Title 1") {
        Text("Page 1")
    }
}
.menuItemSize(.fixed(width: 100, height: 60))
.menuItemSpacing(20)
.menuItemLabelSpacing(30)
.menuBackgroundColor(.white)
.menuInsets(.vertical, 20)
.menuHorizontalAlignment(.center)
.menuPosition(.bottom)
.menuTransition(.scrollAlongside)
.menuInteraction(.swipe)
.contentInteraction(.scrolling)
.contentNavigationOrientation(.vertical)
.selectedScrollPosition(.preferCentered)
.indicatorOptions(.visible(height: 4))
.indicatorColor(.blue)
.borderOptions(.visible(height: 4))
.borderColor(.blue.opacity(0.2))

Basic usage with UIKit

Parchment is built around the PagingViewController class. You can initialize it with an array of view controllers and it will display menu items for each view controller using their title property.

let firstViewController = UIViewController()
let secondViewController = UIViewController()

let pagingViewController = PagingViewController(viewControllers: [
  firstViewController,
  secondViewController
])

See more: Basic usage

Data source

Initializing PagingViewController with an array of view controllers is fine in most cases, but if you have more than a few view controllers you probably don't want to allocate them all up-front. If you're going to display a fixed number of view controllers, you can setup your own data source by implementing PagingViewControllerDataSource:

extension ViewController: PagingViewControllerDataSource {
    func numberOfViewControllers(in pagingViewController: PagingViewController) -> Int {
        return 10
    }

    func pagingViewController(_ pagingViewController: PagingViewController, viewControllerAt index: Int) -> UIViewController {
        return ChildViewController(index: index)
    }

    func pagingViewController(_: PagingViewController, pagingItemAt index: Int) -> PagingItem {
        return PagingIndexItem(title: "View \(index)", index: index)
    }
}

Then you need to set the dataSource property and select the initial item:

let pagingViewController = PagingViewController()
pagingViewController.dataSource = self
pagingViewController.select(index: 0)

Using the data source means Parchment will only allocate view controllers for the currently selected item and any of its siblings. This is a lot more memory efficient than using PagingViewController(viewControllers:) if you have many view controllers.

Read more: Using the data source

Infinite data source

Using PagingViewControllerDataSource means you need to know how many view controllers to display. If you’re creating something like a calendar, the number of view controllers can be infinitely large. In that case you can use the PagingViewControllerInfiniteDataSource protocol:

extension ViewController: PagingViewControllerInfiniteDataSource {
    func pagingViewController(_: PagingViewController, viewControllerFor pagingItem: PagingItem) -> UIViewController {
        return ItemViewController(item: pagingItem)
    }

    func pagingViewController(_: PagingViewController, itemBefore pagingItem: PagingItem) -> PagingItem? {
        guard let item = pagingItem as? Item else { return nil }
        return Item(index: item.index - 1)
    }

    func pagingViewController(_ : PagingViewController, itemAfter pagingItem: PagingItem) -> PagingItem? {
        guard let item = pagingItem as? Item else { return nil }
        return Item(index: item.index + 1)
    }
}

Then set the infiniteDataSource property and select the initial item:

let pagingViewController = PagingViewController()
pagingViewController.infiniteDataSource = self
pagingViewController.select(pagingItem: Item(index: 0))

This pattern is very similar to the UIPageViewControllerDataSource protocol. The main difference is that instead of returning view controllers directly, you have to return an instance conforming to the PagingItem protocol. Parchment will recursively call these methods for the selected PagingItem until the available space is filled up.

Read more: Using the infinite data source

Selecting items

You can select items programmatically using:

func select(pagingItem: PagingItem, animated: Bool = false)

Let’s say you want to select the first item:

override func viewDidLoad() {
  super.viewDidLoad()
  if let first = pagingViewController.children.first as? PagingItem {
    pagingViewController.select(pagingItem: first)
  }
}

Or if you have set the dateSource property, you can select items based on their index:

func select(index: Int, animated: Bool = false)

Reloading data

You can reload data using this method:

func reloadData()

This will keep the previously selected item if it's still part of the updated data. If not, it will select the first item in the list. It will also reload the view controllers displayed in the page view controller. If you only want to reload the menu items, you can use this method:

func reloadMenu()

Calling reloadData() will not work when using PagingViewControllerInfiniteDataSource, as we then need to know what the initial item should be. In that case you should use this method:

func reloadData(around: PagingItem)

This will mark the given paging item as selected and generate new items around it.

Delegate

Parchment provides delegate methods for every step of the transition process through the PagingViewControllerDelegate protocol.

protocol PagingViewControllerDelegate: class {

    func pagingViewController(
        _: PagingViewController,
        isScrollingFromItem currentPagingItem: PagingItem,
        toItem upcomingPagingItem: PagingItem?,
        startingViewController: UIViewController,
        destinationViewController: UIViewController?,
        progress: CGFloat)

    func pagingViewController(
        _: PagingViewController,
        willScrollToItem pagingItem: PagingItem,
        startingViewController: UIViewController,
        destinationViewController: UIViewController)

    func pagingViewController(
        _ pagingViewController: PagingViewController,
        didScrollToItem pagingItem: PagingItem,
        startingViewController: UIViewController?,
        destinationViewController: UIViewController,
        transitionSuccessful: Bool)

    func pagingViewController(
        _ pagingViewController: PagingViewController,
        didSelectItem pagingItem: PagingItem)
}

Size delegate

By default, the size of the menu items is controlled by the menuItemSize property. If you need to control width of each menu item individually you can use the PagingControllerSizeDelegate protocol:

protocol PagingViewControllerSizeDelegate: class {
    func pagingViewController(
        _: PagingViewController,
        widthForPagingItem pagingItem: PagingItem,
        isSelected: Bool) -> CGFloat
}

Then set the sizeDelegate on the PagingViewController:

let pagingViewController = PagingViewController()
pagingViewController.sizeDelegate = self

Customization

Parchment is built to be very flexible. The menu items are displayed using UICollectionView, so they can display pretty much whatever you want. If you need any further customization you can even subclass the collection view layout. All customization is handled by the properties listed below.

Custom cells

To use custom cells you need to subclass PagingCell and register the cell type for a given PagingItem:

let pagingViewController = PagingViewController()
pagingViewController.register(CalendarPagingCell.self, for: CalendarItem.self)

Parchment will then dequeue your custom cell when you return the given PagingItem in your data source. You can register multiple cell types for different PagingItems.

Properties

All customization properties are set on PagingViewController:

let pagingViewController = PagingViewController()
pagingViewController.menuItemSize = .fixed(width: 40, height: 40)
pagingViewController.menuItemSpacing = 10

See Options for all customization options.