Paralayout is a set of simple, useful, and straightforward utilities that enable pixel-perfect layout in iOS. Your designers will love you.
Integrating Paralayout into your iOS project via CocoaPods is simple:
platform :ios, '9.0' pod 'Paralayout'
Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks.
You can install Carthage with Homebrew using the following command:
$ brew update $ brew install carthage
To integrate Paralayout into your Xcode project using Carthage, specify it in your
carthage to build the framework and drag the built
Paralayout.framework into your Xcode project.
Or, manually check out the submodule with
git submodule add email@example.com:Square/Paralayout.git, drag Paralayout.xcodeproj to your workspace, and add Paralayout as a build dependency.
Paralayout is a set of à la carte utilities, of which you can use as much or as little functionality as you like.
UILabel Subclass: Label
Label class makes text look its best, and takes less cumbersome code to configure:
- Style text without directly interacting with
NSParagraphStyle(any more than you want to)
- Get "compact" line wrapping that makes it unnecessary to introduce artificial line breaks into your copy
- Hyperlinks are tappable (no need to use a
UIView Subclass: Hairline
Hairline will size itself correctly on any screen resolution, and provides conveniences for positioning within its superview.
/// Put a line at the bottom of the view, inset 20 points on each side. let separator = Hairline.new(in: view, at: .maxYEdge, inset: 20)
New Value Type: Interpolation
Get the math right for multi-phase layout transitions and animations without tearing your hair out! Under the hood it’s simply a value between 0 and 1, but it makes computing that value, and deriving a new value from it, effortless.
// Determine how far we are into the transition of collapsing the header. let headerCollapseAmount = Interpolation(of: header.frame.height, from: maxHeaderHeight, to: minHeaderHeight) // The icon shrinks to half its usual size... let avatarSize = headerCollapseAmount.interpolate(from: 80, to: 40) avatar.frame.size = CGSize(width: avatarSize, height: avatarSize) // ...as it completely fades out. avatar.alpha = headerCollapseAmount.interpolate(from: 1, to: 0)
New Value Type: AspectRatio
Create an aspect ratio from any size, rect, or width/height value, and use it to compute pixel-snapped frame rectangles.
videoPlayer.frame = AspectRatio.widescreen.rect(toFit: bounds, at: .topCenter, in: view)
These extensions provide numerous conveniences for computing rectangles and snapping coordinates to pixel dimensions. The
ScaleFactor protocol encapsulates the latter, allowing a view to provide the context necessary to align its subviews to pixels. One benefit of this approach is that unit tests can cover both 2x and 3x scale factors regardless of the simulator used to run the test.
In practice, designers adjust margins and text sizes for specific device sizes, not abstract screen dimensions. It may be simplest, for example, to just hide a particular UI element on 3.5" iPhones only, rather than build complex sizing/layout logic that triggers the behavior change at a threshold associated with a small screen.
The extra space within a label above the "cap height" and below the "baseline" of its font is deterministic but non-obvious, especially at different scale factors. The simple
LabelCapInsets value type encapsulates that logic.
UIView Alignment Extensions
The core positioning function (and its numerous derived convenience functions) allows one view to be positioned relative to another view:
titleLabel.align(.leftCenter, with: icon, .rightCenter, horizontalOffset: 8) icon.alignToSuperview(.topCenter, inset: 20)
UIView Sizing Extensions
These methods extend
UIView.sizeToFit() to include constraints, which is particularly useful for labels and other views whose width and height are related to each other.
let labelSize = label.frameSize(thatFits: bounds.insetBy(dx: 20, dy: 20).size, constraints: [ .fixedWidth, .maxHeight ]) titleLabel.wrap(toFitWidth: boundsWidth, margins: 20)
UIView Distribution Extensions
Distribute a set of views vertically or horizontally using fixed and/or proportional spacing between them:
/// Vertically stack an icon, header, and button, with twice as much space at the bottom as the top. selectionScreen.applySubviewDistribution([ 1.flexible, headerIcon, 8.fixed, headerLabel, 1.flexible, button, 2.flexible]) /// Left-align a pair of labels, one above the other, with equal space above the title and below the subtext (despite the subtext being a smaller font). cell.applySubviewDistribution([ 1.flexible, titleLabel, 8.fixed, subtextLabel, 1.flexible ], alignment: .leading(inset: 10)) /// Adjust a "standard" distribution to filter out invisible views (hidden, alpha=0, uninstalled, or empty UILabels), and collapse adjacent spacers. let distribution = ViewDistributionItem.collapsing( 1.flexible, iconFPOView, Metrics.iconMargin.fixed, Metrics.titleTextMargin.fixed, titleLabel, Metrics.titleTextMargin.fixed, Metrics.subtextMargin.fixed, subtextLabel, 1.flexible) /// Equally size a pair of buttons with a hairline divider between them, and size/position them at the bottom of the alert. alert.spreadOutSubviews([ cancelButton, acceptButton ], axis: .horizontal, margin: alert.hairlineWidth, inRect: alert.bounds.slice(fromEdge: .maxYEdge, amount: buttonHeight))
Fixing layout issues is as simple as using the Xcode debugger. Remember that on a 2x device, view frame coordinates will be snapped to half-point boundaries (
x.5 only), while on 3x devices they are on 1/3-point boundaries (
x.667). The offsets used for view alignment do not need to be rounded (and generally shouldn’t be, to avoid accumulating rounding error), but view sizes should be.
- Xcode 8 / Swift 3.0
- iOS 9.0 or later
We’re glad you’re interested in Paralayout, and we’d love to see where you take it. Please read our contributing guidelines prior to submitting a pull request.