📌 FlexLayout is actively updated. So please come often to see latest changes. You can also Star it to be able to retrieve it easily later.

FlexLayout + PinLayout

FlexLayout is a companion of PinLayout. They share a similar syntax and method names. PinLayout is a layout framework greatly inspired by CSS absolute positioning, it is particularly useful for greater fine control and animations. It gives you full control by layouting one view at a time (simple to code and debug).

A view can be layouted using FlexLayout, PinLayout, or both!

PinLayout can layout anything, but in situations where you need to layout many views but don't require PinLayout's finest control nor complex animations, FlexLayout is best fitted.

A view layouted using PinLayout can be embedded inside a FlexLayout's container and reversely. You choose the best layout framework for your situation.

FlexLayout Introduction examples

Example 1:

This example will layout multiples views using column and row flexbox containers.

Two steps to use a flexbox container:

Setup the container: Initialize your flexbox structure. Note that it is also possible to alter it later.

Layout the container: The layout of the container should be done from layoutSubviews() (or willTransition(to: UITraitCollection, ...) and viewWillTransition(to: CGSize, ...)).

First you must layout the flexbox container, i.e. position it and optionally set its size.

FlexLayout principles and philosophy

Flexbox layouting is simple, powerful and fast.

FlexLayout syntax is concise and chainable.

FlexLayout/yoga is incredibly fast, it's even faster than manual layout. See Performance.

The source code structure matches the flexbox structure, making it easier to understand and modify. Flex containers are defined on one line, and its items (children) are imbricated. This makes the flexbox structure much more visual and easy to understand.

Supports left-to-right (LTR) and right-to-left (RTL) languages.

NOTE: FlexLayout wraps facebook/yoga implementation and expose all its features. So note that on this documentation we will refer to FlexLayout, but this also applies to Yoga.

FlexLayout's Performance

As you can see in the following chart, FlexLayout and PinLayout's performance are faster or equal to manual layouting. FlexLayout and PinLayout are between 8x and 12x faster than UIStackViews, and this for all types of iPhone (5S/6/6S/7/8/X)

Variation from CSS flexbox

In many CSS methods and properties name, the keyword flex was added to control name conflicts. FlexLayout removed this keyword for being more concise and removed this unecessary keyword:

FlexLayout Name

CSS Name

React Native Name

direction

flex-direction

flexDirection

wrap

flex-wrap

flexWrap

grow

flex-grow

flexGrow

shrink

flex-shrink

flexShrink

basis

flex-basis

flexBasis

start

flex-start

flexStart

end

flex-end

flexEnd

FlexLayout default properties are sligthly different from CSS flexbox. This table resume these difference:

Property

FlexLayout default value

CSS default value

React Native default value

direction

column

row

column

justifyContent

start

start

start

alignItems

stretch

stretch

stretch

alignSelf

auto

auto

auto

alignContent

start

stretch

start

grow

0

0

0

shrink

0

1

0

basis

0

auto

0

wrap

noWrap

nowrap

noWrap

FlexLayout additions:

addItem()

define()

layout()

isIncludedInLayout()

markDirty()

intrinsicSize

sizeThatFits()

NOTE: FlexLayout doesn't support the flexbox order property. The order is determined by the flex container's UIView.subviews array.

Documentation

Flexbox is pretty easy and straightforward to use. The defining aspect of the flexbox is the ability to alter its items, width, height to best fill the available space on any display device. A flex container expands its items to fill the available free space or shrinks them to prevent overflow.

The flex layout is constituted of parent container referred as flex container and its immediate children which are called flex items. A flex item can also be a flex container, i.e. it is possible to add other flex items to it.

Axes

When working with StackViews you need to think in terms of two axes — the main axis and the cross axis. The main axis is defined by StackView's direction property, and the cross axis runs perpendicular to it.

1. Creation, modification and definition of flexbox items

addItem(:UIView)

addItem(_: UIView) -> Flex
This method adds a flex item (UIView) to a flex container. Internally this method adds the UIView as a subview and enables flexbox.

Usage examples:

view.flex.addItem(imageView).width(100).aspectRatio(1)

addItem()

Applies to: flex containers

Returns: FlexLayout interface of the newly created flex item.

Method:

addItem() -> Flex
This method is similar to addItem(: UIView) except that it also creates the flex item's UIView. Internally the method creates a UIView, adds it as a subview and enables flexbox. This is useful to add a flex item/container easily when you don't need to refer to it later.

Usage examples:

view.flex.addItem().direction(.row).padding(10)

define()

Applies to: flex containers

Parameter: Closure of type (flex: Flex) -> Void

Method:

define(_ closure: (_ flex: Flex) -> Void)
This method is used to structure your code so that it matches the flexbox structure. The method has a closure parameter with a single parameter called flex. This parameter is in fact the view's flex interface. It can be used to adds other flex items and containers.

fitContainer: This is the default mode when no parameter is specified. Children are layouted inside the container's size (width and height).

adjustHeight : In this mode, children are layouted using only the container's width. The container's height will be adjusted to fit the flexbox's children

adjustWidth : In this mode, children are layouted using only the container's height. The container's width will be adjusted to fit the flexbox's children

Usage examples:

rootFlexContainer.flex.layout(mode: .adjustHeight)

2. Flexbox containers properties

This section describes all flex container's properties.

direction()

Applies to: flex containers

Values: column / columnReverse / row / rowReverse

Default value: column

CSS name: flex-direction

Method:

direction(_: Direction)
The direction property establishes the main-axis, thus defining the direction flex items are placed in the flex container.

The direction property specifies how flex items are laid out in the flex container, by setting the direction of the flex container’s main axis. They can be laid out in two main directions, like columns vertically or like rows horizontally.

Note that row and row-reverse are affected by the layout direction (see layoutDirection property) of the flex container. If its text direction is LTR (left to right), row represents the horizontal axis oriented from left to right, and row-reverse from right to left; if the direction is rtl, it's the opposite.

justifyContent()

justifyContent(_: JustifyContent)
The justifyContent property defines the alignment along the main-axis of the current line of the flex container. It helps distribute extra free space leftover when either all the flex items on a line have reached their maximum size. For example, if children are flowing vertically, justifyContent controls how they align vertically.

direction(.column)

direction(.row)

start (default)

Items are packed at the beginning of the main-axis.

end

Items are packed at the end of the main-axis.

center

items are centered along the main-axis.

spaceBetween

Items are evenly distributed in the main-axis; first item is at the beginning, last item at the end.

spaceAround

Items are evenly distributed in the main-axis with equal space around them.

spaceEvenly

Items are evenly distributed in the main-axis with equal space around them.

Usage examples:

alignItems()

Applies to: flex containers

Values: stretch / start / end / center

Default value: stretch

CSS name: align-items

Method:

alignItems(_: AlignItems)
The alignItems property defines how flex items are laid out along the cross axis on the current line. Similar to justifyContent but for the cross-axis (perpendicular to the main-axis). For example, if children are flowing vertically, alignItems controls how they align horizontally.

direction(.column)

direction(.row)

stretch (default)

start

end

center

NOTE: alignItems .baseline is not currently supported by FlexLayout/Yoga.

alignSelf()

Applies to: flex containers

Values: auto / stretch / start / end / center / baseline

Default value: auto

CSS name: align-self

Method:

alignSelf(_: AlignSelf)
The alignSelf property controls how a child aligns in the cross direction, overriding the alignItems of the parent. For example, if children are flowing vertically, alignSelf will control how the flex item will align horizontally.

The auto value means use the flex container alignItems property. See alignItems for documentation of the other values.

wrap()

Applies to: flex containers

Values: noWrap / wrap / wrapReverse

Default value: noWrap

CSS name: flex-wrap

Method:

wrap(_: Wrap)
The wrap property controls whether the flex container is single-lined or multi-lined, and the direction of the cross-axis, which determines the direction in which the new lines are stacked in.

By default, the flex container fits all flex items into one line. Using this property we can change that. We can tell the container to lay out its items in single or multiple lines, and the direction the new lines are stacked in

Reminder: the cross axis is the axis perpendicular to the main axis. Its direction depends on the main axis direction.

direction(.column)

direction(.row)

Description

noWrap (default)

Single-line which may cause the container to overflow. NEW: Flex items are displayed in one row and by default they are shrunk to fit the flex container’s width

wrap

Multi-lines, direction is defined by direction(). NEW: Flex items are displayed in multiple rows if needed from left-to-right and top-to-bottom

wrapReverse

Multi-lines, opposite to direction defined by direction(). NEW: Flex items are displayed in multiple rows if needed from left-to-right and bottom-to-top

Usage examples:

alignContent()

Applies to: flex containers

Values: start / end / center / stretch / spaceBetween / spaceAround

Default value: start

CSS name: align-content

Method:

alignContent(_: AlignContent)
The align-content property aligns a flex container’s lines within the flex container when there is extra space in the cross-axis, similar to how justifyContent aligns individual items within the main-axis.

Note, alignContent has no effect when the flexbox has only a single line.

.inherit
Direction defaults to Inherit on all nodes except the root which defaults to LTR. It is up to you to detect the user’s preferred direction (most platforms have a standard way of doing this) and setting this direction on the root of your layout tree.

.ltr: Layout views from left to right. (Default)

.rtl: Layout views from right to left.

3. Flexbox items properties

This section describe all flex items's properties.

📌 Remembers that flex containers are also flex items, so all these properties also apply to containers.

grow

Applies to: flex items

Default value: 0

CSS name: flex-grow

Method:

grow(_: CGFloat)
The grow property defines the ability for a flex item to grow if necessary. It accepts a unitless value that serves as a proportion. It dictates what amount of the available space inside the flex container the item should take up.

A grow value of 0 (default value) keeps the view's size in the main-axis direction. If you want the view to use the available space set a grow value > 0.

For example, if all items have grow set to 1, every child will set to an equal size inside the container. If you were to give one of the children a value of 2, that child would take up twice as much space as the others.

shrink

Applies to: flex items

Default value: 0

CSS name: flex-shrink

Method:

shrink(_: CGFloat)
It specifies the "flex shrink factor", which determines how much the flex item will shrink relative to the rest of the flex items in the flex container when there isn't enough space on the main-axis.

When omitted, it is set to 0 and the flex shrink factor is multiplied by the flex basis when distributing negative space.

A shrink value of 0 keeps the view's size in the main-axis direction. Note that this may cause the view to overflow its flex container.

Shrink is about proportions. If an item has a shrink of 3, and the rest have a shrink of 1, the item will shrink 3x as fast as the rest.

basis

Applies to: flex items

Default value: 0

CSS name: flex-basis

Method:

basis(_ : CGFloat?)
This property takes the same values as the width and height properties, and specifies the initial size of the flex item, before free space is distributed according to the grow and shrink factors.

Specifying nil set the basis as auto, which means the length is equal to the length of the item. If the item has no length specified, the length will be according to its content

isIncludedInLayout()

Applies to: flex items

Method:

isIncludedInLayout(_ value: Bool)
This property controls dynamically if a flexbox's UIView is included or not in the flexbox layouting. When a flexbox's UIView is excluded, FlexLayout won't layout the view and its children views.

FlexLayout automatically includes the UIView when:

The first time UIView.flex property is accessed

When a child view is added to a flexbox container using addItem(:UIView) or addItem()

display

Applies to: flex items

Method:

display(_: Display)

Set the item display or not, with none value, the item will be hidden and not included in the layout.

markDirty()

Applies to: flex items

Method:

markDirty()
The framework is so highly optimized, that flex items are layouted only when a flex property is changed and when flex container size change. In the event that you want to force FlexLayout to do a layout of a flex item, you can mark it as dirty using markDirty().

Dirty flag propagates to the root of the flexbox tree ensuring that when any item is invalidated its whole subtree will be re-calculated.

Usage examples:

In the case where a UILabel's text is updated, it is needed to mark the label as dirty and relayout the flex container.

left(: CGFloat) / left(: FPercent):
Controls the distance a child’s left edge is from the parent’s left edge.

right(: CGFloat) / right(: FPercent):
Controls the distance a child’s right edge is from the parent’s right edge.

start(: CGFloat) / start(: FPercent):
Controls the distance a child’s start edge is from the parent’s start edge. In left-to-right direction (LTR), it corresponds to the left() property and in RTL to right() property.

end(: CGFloat) / end(: FPercent):
Controls the distance a child’s end edge is from the parent’s end edge. In left-to-right direction (LTR), it corresponds to the right() property and in RTL to left() property.

Using these properties you can control the size and position of an absolute item within its parent. Because absolutely positioned children don’t affect their sibling's layout. Absolute position can be used to create overlays and stack children in the Z axis.

Usage examples:

minWidth(), maxWidth(), minHeight(), maxHeight()

FlexLayout has methods to set the view’s minimum and maximum width, and minimum and maximum height.

Using minWidth, minHeight, maxWidth, and maxHeight gives you increased control over the final size of items in a layout. By mixing these properties with grow, shrink, and alignItems(.stretch), you are able to have items with dynamic size within a range which you control.

An example of when Max properties can be useful is if you are using alignItems(.stretch) but you know that your item won’t look good after it increases past a certain point. In this case, your item will stretch to the size of its parent or until it is as big as specified in the Max property.

Same goes for the Min properties when using shrink. For example, you may want children of a container to shrink to fit on one row, but if you specify a minimum width, they will break to the next line after a certain point (if you are using wrap(.wrap).

Another case where Min and Max dimension constraints are useful is when using aspectRatio.

Methods:

minWidth(_ width: CGFloat?)
The value specifies the view's minimum width of the view in pixels. The value must be non-negative. Call minWidth(nil) to reset the property.

minWidth(_ percent: FPercent)
The value specifies the view's minimum width of the view in percentage of its container width. The value must be non-negative. Call minWidth(nil) to reset the property..

maxWidth(_ width: CGFloat?)
The value specifies the view's maximum width of the view in pixels. The value must be non-negative. Call maxWidth(nil) to reset the property.

maxWidth(_ percent: FPercent)
The value specifies the view's maximum width of the view in percentage of its container width. The value must be non-negative. Call maxWidth(nil) to reset the property.

minHeight(_ height: CGFloat?)
The value specifies the view's minimum height of the view in pixels. The value must be non-negative. Call minHeight(nil) to reset the property.

minHeight(_ percent: FPercent)
The value specifies the view's minimum height of the view in percentage of its container height. The value must be non-negative. Call minHeight(nil) to reset the property.

maxHeight(_ height: CGFloat?)
The value specifies the view's maximum height of the view in pixels. The value must be non-negative. Call maxHeight(nil) to reset the property.

maxHeight(_ percent: FPercent)
The value specifies the view's maximum height of the view in percentage of its container height. The value must be non-negative. Call maxHeight(nil) to reset the property.

Usage examples:

aspectRatio()

AspectRatio is a property introduced by Yoga that don't exist in CSS. AspectRatio solves the problem of knowing one dimension of an element and an aspect ratio, this is very common when it comes to images, videos, and other media types. AspectRatio accepts any floating point value > 0, the default is undefined.

AspectRatio is defined as the ratio between the width and the height of a node e.g. if a node has an aspect ratio of 2 then its width is twice the size of its height.

AspectRatio respects the Min and Max dimensions of an item.

AspectRatio has higher priority than grow.

If AspectRatio, Width, and Height are set then the cross dimension is overridden

Call aspectRatio(nil) to reset the property.

Usage examples:

imageView.flex.aspectRatio(16/9)

6. Margins

By applying Margin to an item you specify the offset a certain edge of the item should have from it’s closest sibling or parent.

Methods:

marginTop(_ value: CGFloat), marginTop(_ percent: FPercent)
Top margin specify the offset the top edge of the item should have from it’s closest sibling (item) or parent (container).

marginLeft(_ value: CGFloat), marginLeft(_ percent: FPercent)
Left margin specify the offset the left edge of the item should have from it’s closest sibling (item) or parent (container).

marginEnd(_ value: CGFloat), marginEnd(_ percent: FPercent)
Set the end margin. In LTR direction, end margin specify the right margin. In RTL direction, end margin specify the left margin.

marginHorizontal(_ value: CGFloat), marginHorizontal(_ percent: FPercent)
Set the left, right, start and end margins to the specified value.

marginVertical(_ value: CGFloat), marginVertical(_ percent: FPercent)
Set the top and bottom margins to the specified value.

margin(_ insets: UIEdgeInsets)
Set all margins using an UIEdgeInsets. This method is particularly useful to set all margins using iOS 11 UIView.safeAreaInsets.

margin(_ insets: NSDirectionalEdgeInsets)
Set all margins using an NSDirectionalEdgeInsets. This method is useful to set all margins using iOS 11 UIView. directionalLayoutMargins when layouting a view supporting RTL/LTR languages.

Usage examples:

7. Paddings

Padding specify the offset children should have from a certain edge on the container.

Methods:

paddingTop(_ value: CGFloat)

paddingLeft(_ value: CGFloat)

paddingBottom(_ value: CGFloat)

paddingRight(_ value: CGFloat)

paddingStart(_ value: CGFloat)

paddingEnd(_ value: CGFloat)

paddingHorizontal(_ value: CGFloat)

paddingVertical(_ value: CGFloat)

padding(_ insets: UIEdgeInsets)
Set all paddings using an UIEdgeInsets. This method is particularly useful to set all paddings using iOS 11 UIView.safeAreaInsets.

padding(_ insets: NSDirectionalEdgeInsets)
Set all paddings using an NSDirectionalEdgeInsets. This method is particularly useful to set all padding using iOS 11 UIView. directionalLayoutMargins when layouting a view supporting RTL/LTR languages.

FlexLayout API Documentation

Example App

FAQ

Q: The flex item overflows or is bigger than its container?A: By default the flex item's shrink value is 0, which keeps the item's current size in the main-axis direction. So that may cause the item to overflow its flex container. To fix that you just have to specify a shrink value bigger than 0:

view.flex.shrink(1)

Q: How to keep the view size (width/height)?A: By default view's flex shrink value is set to 1, which reduce the size of the view if the view is bigger than its flex container in the main-axis direction. If the direction is column, the height is adjusted, if the direction is row, the width is adjusted. Setting this value to 0 will keep the view size in the main-axis direction.

Q: How to apply percentage from a CGFloat, a Float or an Int value?R: Few FlexLayout's method has a parameter of type FPercent. You can easily specify this type of parameter simply by adding the % operator to your value (eg: view.flex.width(25%). It is similar if you have a value of type CGFloat, Float or Int, simply adds the % operator:

Contributing, comments, ideas, suggestions, issues, ....

For issues, please have a look at Yoga's issues. Your issue may have been already reported. If not, it may be a FlexLayout issue. In this case open an issue and we'll let you know if the issue is related to Yoga's implementation.

If you find FlexLayout interesting, thanks to Star it. You'll be able to retrieve it easily later.

If you'd like to contribute, you're welcome!

Installation

CocoaPods

To integrate FlexLayout into your Xcode project using CocoaPods, specify it in your Podfile:

pod 'FlexLayout'

Then, run pod install.

Carthage

To integrate FlexLayout into your Xcode project using Carthage:

Specify in your Cartfile:

github "layoutBox/FlexLayout"

Run carthage update to build frameworks.

Add built FlexLayout.framework in your Xcode project in the Embedded Binaries section.

Changelog

FlexLayout recent history is available in the are documented in the CHANGELOG.