lvgl/docs/src/common-widget-features/layouts/flex.mdx

---
title: Flex
description: "The Flexbox (or Flex for short) is a subset of CSS Flexbox behaviors."
---

## Overview

The Flexbox (or Flex for short) is a subset of CSS Flexbox behaviors.

It can arrange items (child Widgets) into rows or columns (tracks), handle wrapping,
adjust the spacing between items and tracks, handle *grow* to make
item(s) fill remaining space with respect to min/max width and
height.

To make a Widget a Flex container call
<ApiLink name="lv_obj_set_layout" display="lv_obj_set_layout(widget, LV_LAYOUT_FLEX)" />.

Note that the Flex layout feature of LVGL needs to be globally enabled
with <ApiLink name="LV_USE_FLEX" /> in `lv_conf.h`.

## Terms

- **tracks**: rows or columns
- **main direction**: row or column, the direction in which multiple items are
   placed first
- **cross direction**: the direction perpendicular to the **main direction**
- **wrap**: if there is no more space in the track, a new track is started
- **grow**: if set on an item it will "grow" to fill the remaining space in
   the track. The available space will be distributed among items
   respective to their grow value (larger value means more space)
- **gap**: the space between rows and columns or the items on a track

See CSS Flexbox for illustrations showing the meanings of these terms.

<Callout type="info" title="Further Reading">
Learn more about CSS Flexbox.
</Callout>

## Simple Interface

Use the following functions to set and control the Flex layout on any parent Widget.

<Callout type="info">
The parent Widget must be a Flex container for these styles to take effect.
The functions below cause the parent Widget to become a Flex container if it is
not already.
</Callout>

### Flex flow

<LvglExample name="lv_example_flex_flow" path="layouts/flex/lv_example_flex_flow" />

<ApiLink name="lv_obj_set_flex_flow" display="lv_obj_set_flex_flow(widget, flex_flow)" />

The possible values for `flex_flow` are:

- <ApiLink name="LV_FLEX_FLOW_ROW" />: Place the children in a row without wrapping
- <ApiLink name="LV_FLEX_FLOW_COLUMN" />: Place the children in a column without wrapping
- <ApiLink name="LV_FLEX_FLOW_ROW_WRAP" />: Place the children in a row with wrapping
- <ApiLink name="LV_FLEX_FLOW_COLUMN_WRAP" />: Place the children in a column with wrapping
- <ApiLink name="LV_FLEX_FLOW_ROW_REVERSE" />: Place the children in a row without wrapping but in reversed order
- <ApiLink name="LV_FLEX_FLOW_COLUMN_REVERSE" />: Place the children in a column without wrapping but in reversed order
- <ApiLink name="LV_FLEX_FLOW_ROW_WRAP_REVERSE" />: Place the children in a row with wrapping but in reversed order
- <ApiLink name="LV_FLEX_FLOW_COLUMN_WRAP_REVERSE" />: Place the children in a column with wrapping but in reversed order

These values cause the Widget's layout behavior to model CSS Flexbox behavior
by combining flex-direction_ and flex-wrap_ as defined under flex-flow_.

### Flex align

<LvglExample name="lv_example_flex_align" path="layouts/flex/lv_example_flex_align" />

To manage placement of children use
<ApiLink name="lv_obj_set_flex_align" display="lv_obj_set_flex_align(widget,  main_place, cross_place, track_cross_place)" />
which makes the parent Widget model the Flex-container behavior defined [here](https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content).

- `main_place` determines how to distribute the items in their track
   on the main axis. E.g. flush the items to the right on
   <ApiLink name="LV_FLEX_FLOW_ROW_WRAP" />. (It's called
   justify-content_ in CSS.)
- `cross_place` determines how to distribute the items in their track
   on the cross axis. E.g. if the items have different height, align them
   against the bottom of the track. (It's called align-items_ in CSS.)
- `track_cross_place` determines how to distribute the tracks (It's
   called align-content_ in CSS.)

The possible values are:

- <ApiLink name="LV_FLEX_ALIGN_START" />: means left when direction is horizontal, top when vertical (default)
- <ApiLink name="LV_FLEX_ALIGN_END" />: means right when direction is horizontal, bottom when vertical
- <ApiLink name="LV_FLEX_ALIGN_CENTER" />: simply center with respect to direction
- <ApiLink name="LV_FLEX_ALIGN_SPACE_EVENLY" />: items are distributed so
  that the spacing between any two items (and the space to the edges) is
  equal. Does not apply to `track_cross_place`.
- <ApiLink name="LV_FLEX_ALIGN_SPACE_AROUND" />: items are evenly
  distributed in the track with equal space around them. Note that
  visually the spaces are not equal since all the items have equal space
  on both sides.  This makes the space between items double the space
  between edge items and the container's edge.  Does not apply to
  `track_cross_place`.
- <ApiLink name="LV_FLEX_ALIGN_SPACE_BETWEEN" />: items are evenly distributed in
  the track with no space before and after first and last items.  Does not apply
  to `track_cross_place`.

See justify-content_, align-items_ and align-content_ for illustrations of these values.

### Flex grow

<LvglExample name="lv_example_flex_grow" path="layouts/flex/lv_example_flex_grow" />

Flex grow can be used to make one or more children fill available space in the track.
When more than one child Widget have non-zero grow values, all available space will
be distributed in proportion to their respective grow values.  For example, if there
is 400 px space remaining and 3 child Widgets with non-zero grow values:

- `A` with grow = 1
- `B` with grow = 1
- `C` with grow = 2

`A` and `B` will occupy 100 px, and `C` will occupy 200 px.

Flex grow can be set on a child Widget with
<ApiLink name="lv_obj_set_flex_grow" display="lv_obj_set_flex_grow(child, value)" />. `value` needs to be >=
1 or 0 to disable grow on the child.

See flex-grow_ for an illustration of this behavior.

## Style Interface

All Flex-related values are style properties under the hood so you
can use them as you would any other style property.

The following flex related style properties exist:

- <ApiLink name="FLEX_FLOW" />
- <ApiLink name="FLEX_MAIN_PLACE" />
- <ApiLink name="FLEX_CROSS_PLACE" />
- <ApiLink name="FLEX_TRACK_PLACE" />
- <ApiLink name="FLEX_GROW" />

### Internal padding

<LvglExample name="lv_example_flex_internal_padding" path="layouts/flex/lv_example_flex_internal_padding" />

To modify the minimum space flexbox inserts between Widgets, the
following functions can be used to set the flex container padding style:

- <ApiLink name="lv_style_set_pad_row" /> sets padding between rows.
- <ApiLink name="lv_style_set_pad_column" /> sets padding between columns.

These can, for example, be used if you do not want any padding between
Widgets: <ApiLink name="lv_style_set_pad_column" display="lv_style_set_pad_column(&row_container_style, 0)" />

### Right-to-Left writing direction (RTL)

<LvglExample name="lv_example_flex_rtl" path="layouts/flex/lv_example_flex_rtl" />

If the base direction of the container is set the
<ApiLink name="LV_BASE_DIR_RTL" /> the meaning of
<ApiLink name="LV_FLEX_ALIGN_START" /> and
<ApiLink name="LV_FLEX_ALIGN_END" /> is swapped on `ROW` layouts. I.e.
`START` will mean right.

The items on `ROW` layouts, and tracks of `COLUMN` layouts will be
placed from right to left.

## Building a list

<LvglExample name="lv_example_flex_list" path="layouts/flex/lv_example_flex_list" />

You can easily build a list using a column flex with 100% wide buttons and text.

## Forcing a New Track

<LvglExample name="lv_example_flex_new_track" path="layouts/flex/lv_example_flex_new_track" />

You can force Flex to put an item into a new line with
<ApiLink name="lv_obj_add_flag" display="lv_obj_add_flag(child, LV_OBJ_FLAG_FLEX_IN_NEW_TRACK)" />.

## Ignoring layout

<LvglExample name="lv_example_flex_ignore_layout" path="layouts/flex/lv_example_flex_ignore_layout" />

A child can opt out of flex positioning entirely by setting the
<ApiLink name="LV_OBJ_FLAG_IGNORE_LAYOUT" /> flag:

```c
lv_obj_add_flag(child, LV_OBJ_FLAG_IGNORE_LAYOUT);
```

When set, the flex algorithm skips that child — it does not occupy a flex slot
and the remaining children close the gap as if it were absent.  The child keeps
whatever position was set manually with `lv_obj_set_pos()`.  This is useful for
overlay elements (badges, tooltips, decorations) that should float above the
flex content without disturbing the normal flow.


## Edge cases and notes

The following behaviors clarify interactions between flex grow, wrapping and size constraints:

- Grow with LV_SIZE_CONTENT parent: If a flex container's size on the main axis is
   <ApiLink name="LV_SIZE_CONTENT" /> and it contains items with non-zero grow, the grown items
   initially use their own minimum size when determining the container's content size.
   If the container has min/max constraints that force a concrete size, the remaining
   space is then distributed among grow items (respecting each item's min/max).
- Wrapping with grow: For <ApiLink name="LV_FLEX_FLOW_ROW_WRAP" /> and
   <ApiLink name="LV_FLEX_FLOW_COLUMN_WRAP" />, wrapping is used as expected even when the
   object is grown in the same direction and its size in that direction is
   <ApiLink name="LV_SIZE_CONTENT" />. In this case the <ApiLink name="LV_SIZE_CONTENT" /> constraint is
   ignored to be consistent with how the object size is calculated, and the grown size is used.
- Min/max as content or percent: Item min/max width/height can be set to
   <ApiLink name="LV_SIZE_CONTENT" /> or <ApiLink name="LV_PCT" display="LV_PCT(x)" />. These constraints are respected
   during grow and wrapping and can clamp size of grown items.
- Gaps with zero-size grow: Padding/gap is still applied even if a grown item ends up
   with zero size on the main axis; this matches CSS flex behavior.