Skip to content

UIStackView ​

UIStackView represents a stack view, a container that arranges the subviews you put in it into a row or a column along one direction and automatically positions and sizes each of them. It displays nothing itself.

The direction is set by axis: 'horizontal' makes a row, 'vertical' makes a column. The spacing between subviews is set by spacing, in pt, and does not scale with the font size. How space is distributed along the direction of arrangement is set by distribution; how items are aligned perpendicular to it is set by alignment.

Subviews that take part in the arrangement are called arranged subviews and are added with addArrangedSubview(). They are arranged in the order they were added. The stack view creates constraints (the position relationships between views in Auto Layout) for its arranged subviews, so you do not write, and should not write, their positions.

Inheritance: EventTarget → NSObject → UIResponder → UIView → UIStackView

For how to build common layouts with it, see the guide Arranging views in a row or column.

Constructor ​

UIStackView()

Creates a stack view, optionally with an initial set of arranged subviews.

Instance properties ​

Also inherits the properties of UIView. The inherited properties commonly used with stack views are isHidden (on arranged subviews), directionalLayoutMargins (padding), and translatesAutoresizingMaskIntoConstraints.

PropertyDescription
axisRow or column
distributionHow space along the direction of arrangement is divided
alignmentHow items are aligned perpendicular to the direction of arrangement
spacingThe spacing between adjacent items
isBaselineRelativeArrangementIn a vertical arrangement, measures spacing from text baselines
isLayoutMarginsRelativeArrangementArranges items inside the padding
arrangedSubviews read-onlyAll arranged subviews, in order

Instance methods ​

Also inherits the methods of UIView. Remove an arranged subview with the inherited removeFromSuperview().

MethodDescription
addArrangedSubview()Adds to the end of the arrangement
insertArrangedSubview()Inserts at a given position in the arrangement
removeArrangedSubview()Removes from the arrangement; the view is still a subview of the stack view
setCustomSpacing()Sets the spacing after one particular item
customSpacingAfterView()Reads the custom spacing set after an item

Events ​

UIStackView fires no events of its own. traitchange, inherited from UIView, fires as usual.

Concepts ​

Main axis and cross axis ​

axis sets the direction of arrangement, called the main axis. The perpendicular direction is called the cross axis.

axisMain axisCross axis
'horizontal'Horizontal, left to rightVertical
'vertical'Vertical, top to bottomHorizontal

distribution and spacing control the main axis; alignment controls the cross axis.

Arranged subviews and subviews ​

A stack view has two lists:

ListContentsWhat the order means
subviewsAll subviews. Inherited from UIViewStacking order; later ones cover earlier ones
arrangedSubviewsThe subviews that take part in the arrangement, called arranged subviews. A subset of subviewsArrangement order, left to right or top to bottom

How each operation affects the two lists:

OperationarrangedSubviewssubviews
stack.addArrangedSubview(view)AddedAdded
stack.insertArrangedSubview(view, { atIndex })AddedAdded
new UIStackView([view])AddedAdded
stack.removeArrangedSubview(view)RemovedUnchanged
view.removeFromSuperview()RemovedRemoved
stack.addSubview(view)UnchangedAdded

So:

  • To add an arranged subview, call only addArrangedSubview(); you do not also need addSubview().
  • To remove an arranged subview, call only removeFromSuperview(); you do not also need removeArrangedSubview().
  • A view added with addSubview() is not an arranged subview, and the stack view does not position it.

Where an arranged subview's size comes from ​

The stack view divides space according to each arranged subview's "intrinsic size". The intrinsic size is the size a view calculates from its own content: how long the text is, how wide the text on a button is. When the content changes, the intrinsic size changes, and the stack view rearranges at the next layout pass.

  • Views such as UILabel, UIButton, and UIImageView have an intrinsic size.
  • A plain UIView has no intrinsic size. As an arranged subview, either the stack view must stretch it (alignment = 'fill', distribution = 'fillEqually'), or you must give it a width and height with constraints. With neither, its size is 0 and it cannot be seen.

The stack view does two things to its arranged subviews:

  • Sets their translatesAutoresizingMaskIntoConstraints to false.
  • Creates constraints for them. So do not write constraints that determine their position; write only a width or height when needed.

The stack view's own position is not its own business. Like any other view, it is positioned with constraints or frame. When it is an arranged subview of another stack view, the outer stack view positions it. In any direction not limited by a constraint, the stack view's size is determined by its arranged subviews.

It displays nothing itself ​

A stack view only arranges; it draws nothing itself. Setting backgroundColor or layer.cornerRadius on it has no visible effect.

For a background color and rounded corners, wrap it in a plain UIView; see Adding a background and rounded corners in the guide.

The stack view's own position and size ​

A stack view only manages the arranged subviews inside it, not itself. Its own position must be set with constraints or frame, like any other view. When using constraints, set the stack view's own translatesAutoresizingMaskIntoConstraints to false; it does not do this for itself. Without this line, the whole stack view has size 0, nothing inside it can be seen, and the console prints nothing.

You can leave out the stack view's size. In any direction where no constraint limits the width or height, the stack view's size is determined by its arranged subviews: their sizes plus the spacing. Measured: a vertical stack view with 12 rows, each 36 pt tall, with 6 pt spacing and no height written, has a calculated height of 498 pt (12 × 36 + 11 × 6).

When a stack view is an arranged subview of another stack view, the outer one positions it, and you write nothing.

Hidden arranged subviews give up their space ​

Setting an arranged subview's isHidden to true makes it give up its space, and the other items rearrange automatically. Setting it back to false returns it to its original position. Measured: in a row of three equal-width items, after hiding the middle one, the hidden item's width is 0, the other two split the whole row, and there is only one spacing between them. A hidden arranged subview is still in arrangedSubviews.

Views not in a stack view do not behave this way; after being hidden they still occupy their original space.

Only one row or one column ​

A stack view does not wrap. When a row does not fit, the items are squeezed narrower; they do not wrap to the next line (the squeezing effect is not verified in the simulator). When you need multiple rows, JS decides how many items go in each row; see Arranging in multiple rows in the guide.

A stack view does not scroll when its content goes past the screen; put it in a UIScrollView.

Examples ​

A column with a line of text and a row of color blocks ​

The following code starts from a blank app and puts a column near the top of the screen: the first item is a line of text, and the second is a row of three equal-width color blocks.

js
application.addEventListener('sceneconnect', (e) => {
  // Create the window and view controller. Every app needs these lines
  const win = new UIWindow(e.scene);
  const page = new UIViewController();
  page.view.backgroundColor = 'systemBackground';
  win.rootViewController = page;
  win.makeKeyAndVisible();

  // 1. Create a vertical stack view with 16 pt between items
  const column = new UIStackView();
  column.axis = 'vertical';
  column.spacing = 16;

  // 2. First item: a line of text
  const title = new UILabel();
  title.text = 'Three equal-width blocks';
  column.addArrangedSubview(title);

  // 3. Second item: a horizontal stack view holding three color blocks
  const [red, orange, teal] = ['systemRed', 'systemOrange', 'systemTeal'].map((color) => {
    const block = new UIView();
    block.backgroundColor = color;
    return block;
  });
  const row = new UIStackView([red, orange, teal]);
  row.axis = 'horizontal';
  row.distribution = 'fillEqually';   // Three equal widths
  row.spacing = 12;                   // 12 pt between items
  column.addArrangedSubview(row);

  // 4. Put the outermost stack view on the page and position it with constraints
  column.translatesAutoresizingMaskIntoConstraints = false;
  page.view.addSubview(column);
  const safe = page.view.safeAreaLayoutGuide;
  NSLayoutConstraint.activateConstraints([
    column.topAnchor.constraintEqualToAnchor(safe.topAnchor, { constant: 16 }),
    column.leadingAnchor.constraintEqualToAnchor(safe.leadingAnchor, { constant: 16 }),
    column.trailingAnchor.constraintEqualToAnchor(safe.trailingAnchor, { constant: -16 }),
    // The color blocks have no height of their own, so give the row a height
    row.heightAnchor.constraintEqualToConstant(44),
  ]);
});

Effect

  • Near the top of the screen, 16 pt below the top of the safe area, is the line of text "Three equal-width blocks".
  • 16 pt below the text is a row of three color blocks: red, orange, teal. Each is 44 pt tall.
  • The three blocks have the same width, with 12 pt between each pair. The row is 16 pt from the screen edge on each side.
  • Each block's width is (row width − 2 × 12) ÷ 3.

This code has not been run as a whole in the simulator. Every API it uses has been run in the acceptance tests, and "three equal widths" and the width calculation were checked there.

The four steps are: create the stack view, add the arranged subviews, nest another stack view, and position the outermost one with constraints. For the constraints in step 4 and safeAreaLayoutGuide (the safe area, the region of the screen not covered by the notch or the home indicator), see NSLayoutConstraint and UIView.

Note: The line column.translatesAutoresizingMaskIntoConstraints = false in step 4 is required. This property defaults to true, meaning "position this view by its frame", and a new view's frame is 0 × 0, so the whole column would be invisible. The arranged subviews in the stack view (title, row, and the three blocks) are set automatically by the stack view; you do not write it for them.

This example gives column no height and gives title no constraints at all. column's height is determined by the heights of its two arranged subviews plus the spacing, and title's height is determined by its text.

For more patterns, see the guide Arranging views in a row or column.

Corresponding iOS API ​

Use this table to look up the JS equivalent when following Apple's documentation or iOS sample code.

ObjCJS
[[UIStackView alloc] init]new UIStackView()
[[UIStackView alloc] initWithArrangedSubviews:@[a, b]]new UIStackView([a, b])
stack.axis = UILayoutConstraintAxisVerticalstack.axis = 'vertical'
stack.distribution = UIStackViewDistributionFillEquallystack.distribution = 'fillEqually'
stack.alignment = UIStackViewAlignmentCenterstack.alignment = 'center'
stack.alignment = UIStackViewAlignmentTopstack.alignment = 'top', which reads back as 'leading'
stack.spacing = 12stack.spacing = 12
stack.spacing = UIStackViewSpacingUseSystemstack.spacing = 'system'
stack.baselineRelativeArrangement = YESstack.isBaselineRelativeArrangement = true
stack.layoutMarginsRelativeArrangement = YESstack.isLayoutMarginsRelativeArrangement = true
stack.directionalLayoutMargins = NSDirectionalEdgeInsetsMake(16, 16, 16, 16)stack.directionalLayoutMargins = new NSDirectionalEdgeInsets(16, 16, 16, 16)
stack.arrangedSubviewsstack.arrangedSubviews
[stack addArrangedSubview:v]stack.addArrangedSubview(v)
[stack insertArrangedSubview:v atIndex:1]stack.insertArrangedSubview(v, { atIndex: 1 })
[stack removeArrangedSubview:v]stack.removeArrangedSubview(v)
[stack setCustomSpacing:40 afterView:v]stack.setCustomSpacing(40, { afterView: v })
[stack setCustomSpacing:UIStackViewSpacingUseDefault afterView:v]stack.setCustomSpacing('default', { afterView: v })
[stack customSpacingAfterView:v]stack.customSpacingAfterView(v)

The rule for converting enum values: drop the type prefix and lowercase the first letter. UIStackViewDistributionEqualSpacing is written 'equalSpacing'.

Comparison with CSS ​

This table is only for people familiar with flexbox to look up equivalents; the rest of the page does not depend on it.

CSSUIStackViewDifference
display: flexnew UIStackView()Subviews must be added with addArrangedSubview()
flex-direction: row / columnaxis = 'horizontal' / 'vertical'
gapspacingOnly pt or 'system'; no em or percentages
justify-content plus each item's flex-growdistributionNo values corresponding to center, flex-end, or space-around
justify-content: space-betweendistribution = 'equalSpacing'
flex-growThe arranged subview's content hugging priorityWorks the other way round: the lower the value, the more easily it stretches. Not proportional
align-items: stretchalignment = 'fill'
align-items: flex-start / center / flex-endalignment = 'leading' / 'center' / 'trailing'
align-items: baselinealignment = 'firstBaseline'Only works in a horizontal arrangement
paddingdirectionalLayoutMargins, with isLayoutMarginsRelativeArrangement set to trueThe default is 8 pt on each edge, not 0
display: noneisHidden = true on the arranged subview
flex-wrapNone
align-self, orderNoneThe whole stack view has only one alignment, and the order is the order of adding
The container's own background, border-radiusNot displayedWrap it in a plain view

See also ​

  • Arranging views in a row or column: equal widths, filling remaining space, alignment, hiding, padding, background, nesting
  • UIView: the inherited members; isHidden, removeFromSuperview(), and content priorities are all there
  • NSLayoutConstraint: positioning the stack view itself needs constraints
  • UIScrollView: put the stack view in one when its content goes past the screen
  • UILabel: the most common arranged subview; it has an intrinsic size
  • Enums: the general rules for string values and the format of warnings and errors for invalid values
  • Units: what pt is