Understanding the box model and flexbox is essential to understanding UI Toolkit in Unity. In CSS, you have more properties, display types, and alternative box models. In USS, it is made simple, but also more limited. There is only one box model, and everything is either DisplayStyle.Flex, or DisplayStyle.None.

The box model is a core concept which describes how UXML elements are calculated as boxes in the layout, and how different properties affect that box. Everything in both USS and CSS is a box, but unlike CSS, USS only supports one box model, the border box.

When hovering over an element in the UI Builder:

  • The blue area will be the space the content is placed in (Child elements)
  • The green will be the padding (Spacing INSIDE the current element)
  • The yellow will be the border
  • The orange will be the margin (Spacing OUTSIDE the element)

The element size you specify with width + height will be a combination of content + padding + border. Margin is excluded from this as it is considered outside of the element and used to space one element away from other elements in the layout.

Margin
Padding
Content

If an element has the USS below, then the real dimensions of the content container will be 210px by 210px. 20px on either side will be taken away for padding, and 5 px on either side will be taken away for border. The margin is considered outside of the element, and will not affect the size of the content container.

USS

An element will always maintain space in the layout as long as it is set as DisplayStyle.Flex. Even if the opacity is set to 0, or the visibility is set to hidden.

opacity 0
opacity 100

UXML

visible

UXML

Flexbox is a layout system to arrange elements in the UXML document. The layout system is composed of a main axis, and a cross axis. The main axis is the direction of the flex layout (flex-row, flex-row-reversed, flex-col, or flex-col-reversed) and the direction the elements will be ordered in. The cross axis is the axis perpendicular to this.

Explanations of individual flex properties, and their behaviour are covered more in-depth with better examples in each property's page. A good starting point is Flex Direction.

0
1
2
3

Main Start

Main End

Cross Start

Cross End

By default, elements are organized in a column starting from main start and ending at main end.

  • justify-content will affect layout along the main axis
  • align-items will affect layout along the cross axis
  • align-self will affect layout along the cross axis individually
  • align-content will affect layout along the cross axis

UXML

0
1
2
3

Cross Start

Cross End

Main Start

Main End

The flex direction property will change the orientation and order of the main / cross axes, and corresponding starts / ends. Taking the example above, a change to flex-row will swap the main and cross axes.

If the change was simply to flex-col-reverse, then the positions of main start, main end, cross start, and cross end would swap, but the axes would not. The order VisualElements are defined in UXML is unchanged.

UXML