Skip to content

Commit e84b1bd

Browse files
spliffonekfenner
spliffone
authored and
kfenner
committed
docs(flex): document flex utils
1 parent 05a940f commit e84b1bd

22 files changed

+946
-0
lines changed

‎docs/fundamentals/styles/flex.md‎

Lines changed: 330 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,330 @@
1+
# Flex
2+
3+
Flexbox is a powerful one-dimensional layout system that provides efficient ways to align, distribute, and manage space among items in a container, even when their sizes are unknown or dynamic. Element provides a comprehensive suite of utility classes to create responsive layouts quickly without writing custom CSS.
4+
5+
The document covers the following flexbox capabilities:
6+
7+
- **Display & Direction** - Create flex containers and control item flow direction
8+
- **Alignment** - Align items along the main and cross axes
9+
- **Spacing & Sizing** - Control how items grow, shrink, and fill available space
10+
- **Ordering & Wrapping** - Reorder items visually and control multi-line behavior
11+
12+
All utilities support responsive variations using breakpoint modifiers (e.g., `.d-{breakpoint}-flex`), allowing you to adapt layouts across different screen sizes.
13+
14+
## Enable flex behaviors
15+
16+
Use display utility classes to turn an element into a flex container, making its direct children flex items. Once a flex container is established, you can further customize its behavior and the layout of its items using additional flexbox utility classes.
17+
18+
```html
19+
<div class="d-flex p-2">This is a flexbox container!</div>
20+
```
21+
22+
```html
23+
<div class="d-inline-flex p-2">This is a inline flexbox container!</div>
24+
```
25+
26+
For faster mobile-friendly development, use responsive variations for `.d-flex` and `.d-inline-flex` based on breakpoints:
27+
28+
- `.d-{breakpoint}-flex`
29+
- `.d-{breakpoint}-inline-flex`
30+
31+
## Align items
32+
33+
Use `align-items` utility classes on flex containers to control how flex items are aligned along the cross axis (vertically by default, or horizontally when using `flex-direction: column`).
34+
Available options include `start`, `end`, `center`, `baseline`, and `stretch` (the default).
35+
36+
```html
37+
<div class="d-flex align-items-start">...</div>
38+
<div class="d-flex align-items-end">...</div>
39+
<div class="d-flex align-items-center">...</div>
40+
<div class="d-flex align-items-baseline">...</div>
41+
<div class="d-flex align-items-stretch">...</div>
42+
```
43+
44+
<si-docs-component example="flex/flex-align-items" height="150"></si-docs-component>
45+
46+
| Class | Responsive variation |
47+
|--------|----------------------|
48+
| `.align-items-start` | `.align-items-{breakpoint}-start` |
49+
| `.align-items-end` | `.align-items-{breakpoint}-end` |
50+
| `.align-items-center` | `.align-items-{breakpoint}-center` |
51+
| `.align-items-baseline` | `.align-items-{breakpoint}-baseline` |
52+
| `.align-items-stretch` | `.align-items-{breakpoint}-stretch` |
53+
54+
## Align self
55+
56+
Use `align-self` utility classes on individual flex items to override the container’s cross-axis alignment for that item only.
57+
Available options include `start`, `end`, `center`, `baseline`, and `stretch` (the default).
58+
The cross axis is vertical by default, or horizontal when using `flex-direction: column`.
59+
60+
```html
61+
<div class="align-self-start">Aligned flex item</div>
62+
<div class="align-self-end">Aligned flex item</div>
63+
<div class="align-self-center">Aligned flex item</div>
64+
<div class="align-self-baseline">Aligned flex item</div>
65+
<div class="align-self-stretch">Aligned flex item</div>
66+
```
67+
68+
<si-docs-component example="flex/flex-align-self" height="150"></si-docs-component>
69+
70+
## Auto margins
71+
72+
Auto margins in flexbox are a convenient way to control spacing and alignment of flex items within a container.
73+
By applying margin utilities such as `.me-auto` (margin-end auto) or `.ms-auto` (margin-start auto) to specific flex items, you can easily push items to one side or distribute available space between them.
74+
The examples below demonstrate: the default layout with no auto margins, using `.me-auto` to push subsequent items to the right, and using `.ms-auto` to push the last item to the far right.
75+
These techniques help you achieve common layout patterns without custom CSS.
76+
77+
```html
78+
<div class="d-flex mb-3">
79+
<div>Item 1</div>
80+
<div>Item 2</div>
81+
<div>Item 3</div>
82+
</div>
83+
<div class="d-flex mb-3">
84+
<div class="me-auto">Item 1</div>
85+
<div>Item 2</div>
86+
<div>Item 3</div>
87+
</div>
88+
<div class="d-flex mb-3">
89+
<div>Item 1</div>
90+
<div>Item 2</div>
91+
<div class="ms-auto">Item 3</div>
92+
</div>
93+
```
94+
95+
<si-docs-component example="flex/flex-auto-margins" height="150"></si-docs-component>
96+
97+
## Align items with auto margins
98+
99+
To vertically position a specific flex item at the top or bottom of a flex container, combine `align-items`, `flex-direction: column`, and auto margins.
100+
Applying `margin-top: auto` pushes an item to the bottom, while `margin-bottom: auto` pushes it to the top.
101+
This technique lets you control vertical alignment of individual items without extra wrappers or custom CSS.
102+
103+
```html
104+
<div class="d-flex align-items-start flex-column mb-3" style="height: 200px;">
105+
<div class="mb-auto">Item 1</div>
106+
<div>Item 2</div>
107+
<div>Item 3</div>
108+
</div>
109+
110+
<div class="d-flex align-items-end flex-column mb-3" style="height: 200px;">
111+
<div>Item 1</div>
112+
<div>Item 2</div>
113+
<div class="mt-auto">Item 3</div>
114+
</div>
115+
```
116+
117+
<si-docs-component example="flex/flex-align-items-auto-margins" height="200"></si-docs-component>
118+
119+
## Align content
120+
121+
Use `align-content` utilities on flex containers to control how multiple rows of flex items are spaced along the cross axis. Options include `start` (default), `end`, `center`, `between`, `around`, and `stretch`.
122+
These utilities are most effective when the container has wrapping enabled (`flex-wrap: wrap`) and contains enough items to create multiple rows.
123+
124+
> **Note:** `align-content` has no visible effect if your flex container only has a single row of items.
125+
126+
```html
127+
<div class="d-flex align-content-start">...</div>
128+
<div class="d-flex align-content-end">...</div>
129+
<div class="d-flex align-content-center">...</div>
130+
<div class="d-flex align-content-between">...</div>
131+
<div class="d-flex align-content-around">...</div>
132+
<div class="d-flex align-content-stretch">...</div>
133+
```
134+
135+
<si-docs-component example="flex/flex-align-content" height="200"></si-docs-component>
136+
137+
| Class | Responsive variation |
138+
|--------|----------------------|
139+
| `.align-content-start` | `.align-content-{breakpoint}-start` |
140+
| `.align-content-end` | `.align-content-{breakpoint}-end` |
141+
| `.align-content-center` | `.align-content-{breakpoint}-center` |
142+
| `.align-content-between` | `.align-content-{breakpoint}-between` |
143+
| `.align-content-around` | `.align-content-{breakpoint}-around` |
144+
| `.align-content-stretch` | `.align-content-{breakpoint}-stretch` |
145+
146+
## Fill
147+
148+
Apply the `.flex-fill` class to multiple sibling elements within a flex container to make each item expand and share the available horizontal space equally. This ensures that all items grow to fill the container, regardless of their content size, resulting in a balanced layout without custom CSS.
149+
150+
```html
151+
<div class="d-flex">
152+
<div class="flex-fill">Item with a lot of content</div>
153+
<div class="flex-fill">Item</div>
154+
<div class="flex-fill">Item</div>
155+
</div>
156+
```
157+
158+
<si-docs-component example="flex/flex-fill" height="150"></si-docs-component>
159+
160+
| Class | Responsive variation |
161+
|--------|----------------------|
162+
| `.flex-fill` | `.flex-{breakpoint}-fill` |
163+
164+
## Direction
165+
166+
Control the direction in which flex items are laid out within a flex container using direction utility classes.
167+
By default, flex containers use a horizontal (`row`) direction, but you may need to explicitly set or override this—especially for responsive designs or when reversing the item order.
168+
169+
- Use `.flex-row` to arrange items horizontally (left to right).
170+
- Use `.flex-row-reverse` to arrange items horizontally in reverse order (right to left).
171+
- Use `.flex-column` to stack items vertically (top to bottom).
172+
- Use `.flex-column-reverse` to stack items vertically in reverse order (bottom to top).
173+
174+
These utilities help you quickly adapt layouts to different design requirements without writing custom CSS.
175+
176+
```html
177+
<div class="d-flex flex-row mb-3">
178+
<div>Item 1</div>
179+
<div>Item 2</div>
180+
<div>Item 3</div>
181+
</div>
182+
<div class="d-flex flex-row-reverse">
183+
<div>Item 1</div>
184+
<div>Item 2</div>
185+
<div>Item 3</div>
186+
</div>
187+
```
188+
189+
Use `.flex-column` to set a vertical direction, or `.flex-column-reverse` to start the vertical direction from the opposite side.
190+
191+
```html
192+
<div class="d-flex flex-column mb-3">
193+
<div>Item 1</div>
194+
<div>Item 2</div>
195+
<div>Item 3</div>
196+
</div>
197+
<div class="d-flex flex-column-reverse">
198+
<div>Item 1</div>
199+
<div>Item 2</div>
200+
<div>Item 3</div>
201+
</div>
202+
```
203+
204+
| Class | Responsive variation |
205+
|--------|----------------------|
206+
| `.flex-row` | `.flex-{breakpoint}-row` |
207+
| `.flex-row-reverse` | `.flex-{breakpoint}-row-reverse` |
208+
| `.flex-column` | `.flex-{breakpoint}-column` |
209+
| `.flex-column-reverse` | `.flex-{breakpoint}-column-reverse` |
210+
211+
<si-docs-component example="flex/flex-direction" height="100"></si-docs-component>
212+
213+
## Grow and shrink
214+
215+
Use `.flex-grow-*` utilities to control how much a flex item expands to fill available space within a flex container.
216+
Applying `.flex-grow-1` to an item allows it to grow and occupy any remaining space, while items without this class will only take up as much space as their content requires.
217+
218+
```html
219+
<div class="d-flex">
220+
<div class="flex-grow-1">Item 1</div>
221+
<div>Item 2</div>
222+
<div>Item 3</div>
223+
</div>
224+
```
225+
226+
Use `.flex-shrink-*` utility classes to control whether a flex item can shrink when there isn’t enough space in a flex container.
227+
In the example below, the second flex item uses `.flex-shrink-1`, allowing it to shrink and wrap its contents onto a new line.
228+
This makes more space available for the first flex item, which uses `.w-100` to take up the full width.
229+
230+
```html
231+
<div class="d-flex">
232+
<div class="w-100">Item</div>
233+
<div class="flex-shrink-1">Item</div>
234+
</div>
235+
```
236+
237+
| Class | Responsive variation |
238+
|--------|----------------------|
239+
| `.flex-{grow|shrink}-0` | `.flex-{breakpoint}-{grow|shrink}-0` |
240+
| `.flex-{grow|shrink}-1` | `.flex-{breakpoint}-{grow|shrink}-1` |
241+
242+
## Justify content
243+
244+
Use `justify-content` utility classes on flex containers to control how flex items are distributed along the main axis (horizontal by default, vertical if using `flex-direction: column`).
245+
These classes let you align items to the start, end, center, or distribute them with equal spacing using `between`, `around`, or `evenly`.
246+
247+
```html
248+
<div class="d-flex justify-content-start">...</div>
249+
<div class="d-flex justify-content-end">...</div>
250+
<div class="d-flex justify-content-center">...</div>
251+
<div class="d-flex justify-content-between">...</div>
252+
<div class="d-flex justify-content-around">...</div>
253+
<div class="d-flex justify-content-evenly">...</div>
254+
```
255+
256+
<si-docs-component example="flex/flex-justify-content" height="150"></si-docs-component>
257+
258+
| Class | Responsive variation |
259+
|--------|----------------------|
260+
| `.justify-content-start` | `.justify-content-{breakpoint}-start` |
261+
| `.justify-content-end` | `.justify-content-{breakpoint}-end` |
262+
| `.justify-content-center` | `.justify-content-{breakpoint}-center` |
263+
| `.justify-content-between` | `.justify-content-{breakpoint}-between` |
264+
| `.justify-content-around` | `.justify-content-{breakpoint}-around` |
265+
| `.justify-content-evenly` | `.justify-content-{breakpoint}-evenly` |
266+
267+
## Order
268+
269+
Use `order` utility classes to visually rearrange the sequence of flex items within a container, independent of their order in the HTML markup.
270+
These utilities are helpful for responsive layouts where you want to change the display order of items at different breakpoints, highlight specific content, or create more accessible tab flows.
271+
The provided classes let you move an item to the first or last position, or reset it to its original DOM order.
272+
For more granular control, you can assign integer values from 0 to 5; if you need additional values, add custom CSS.
273+
274+
```html
275+
<div class="d-flex flex-nowrap">
276+
<div class="order-3 p-2">Item 1</div>
277+
<div class="order-2 p-2">Item 2</div>
278+
<div class="order-1 p-2">Item 3</div>
279+
</div>
280+
```
281+
282+
<si-docs-component example="flex/flex-order" height="150"></si-docs-component>
283+
284+
| Class | Responsive variation |
285+
|--------|----------------------|
286+
| `.order-0` | `.order-{breakpoint}-0` |
287+
| `.order-1` | `.order-{breakpoint}-1` |
288+
| `.order-2` | `.order-{breakpoint}-2` |
289+
| `.order-3` | `.order-{breakpoint}-3` |
290+
| `.order-4` | `.order-{breakpoint}-4` |
291+
| `.order-5` | `.order-{breakpoint}-5` |
292+
293+
You can also use responsive `.order-first` and `.order-last` classes to move an element to the start (`order: -1`) or end (`order: 6`) of the flex container at specific breakpoints.
294+
295+
| Class | Responsive variation |
296+
|--------|----------------------|
297+
| `.order-first` | `.order-{breakpoint}-first` |
298+
| `.order-last` | `.order-{breakpoint}-last` |
299+
300+
## Wrap
301+
302+
Control how flex items wrap within a flex container using wrap utilities. Use `.flex-nowrap` to keep all items on a single line (default browser behavior), which can cause items to overflow if there isn’t enough space.
303+
Apply `.flex-wrap` to allow items to move onto multiple lines as needed, preventing overflow and improving responsiveness.
304+
Use `.flex-wrap-reverse` to wrap items onto multiple lines in the reverse direction, which can be useful for specific layout requirements.
305+
306+
```html
307+
<div class="d-flex flex-nowrap">
308+
...
309+
</div>
310+
```
311+
312+
```html
313+
<div class="d-flex flex-wrap">
314+
...
315+
</div>
316+
```
317+
318+
```html
319+
<div class="d-flex flex-wrap-reverse">
320+
...
321+
</div>
322+
```
323+
324+
<si-docs-component example="flex/flex-wrap" height="150"></si-docs-component>
325+
326+
| Class | Responsive variation |
327+
|--------|----------------------|
328+
| `.flex-nowrap` | `.flex-{breakpoint}-nowrap` |
329+
| `.flex-wrap` | `.flex-{breakpoint}-wrap` |
330+
| `.flex-wrap-reverse` | `.flex-{breakpoint}-wrap-reverse` |

‎mkdocs.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,8 @@ nav:
3434
- Elevation: 'fundamentals/elevation.md'
3535
- Icons: 'fundamentals/icons.md'
3636
- Localization: 'fundamentals/localization.md'
37+
- Styles:
38+
- Flex: 'fundamentals/styles/flex.md'
3739
- UX Writing:
3840
- Overview: 'fundamentals/ux-text-style-guide/index.md'
3941
- Basics: 'fundamentals/ux-text-style-guide/basics.md'

0 commit comments

Comments
 (0)