0
# Layout and Containers
1

2
Functions for organizing app layout including columns, containers, sidebars, tabs, and expandable sections. These components provide the structural foundation for organizing content and creating sophisticated user interfaces.
3

4
## Capabilities
5

6
### Layout Functions
7

8
Core layout functions for organizing content in columns, rows, and structured arrangements.
9

10
```python { .api }
11
def columns(spec, *, gap="small"):
12
    """
13
    Create column layout for horizontal content arrangement.
14

15
    Args:
16
        spec (int or list): Number of columns or list of column widths
17
        gap (str): Gap size between columns ("small", "medium", "large")
18

19
    Returns:
20
        list[DeltaGenerator]: List of column containers
21
    """
22

23
def tabs(tab_list):
24
    """
25
    Create tab container with multiple named tabs.
26

27
    Args:
28
        tab_list (list): List of tab names/labels
29

30
    Returns:
31
        list[DeltaGenerator]: List of tab containers
32
    """
33
```
34

35
Example usage:
36
```python
37
# Create equal-width columns
38
col1, col2, col3 = st.columns(3)
39
with col1:
40
    st.write("Column 1")
41
with col2:
42
    st.write("Column 2")
43

44
# Create tabs
45
tab1, tab2 = st.tabs(["Data", "Chart"])
46
with tab1:
47
    st.dataframe(data)
48
with tab2:
49
    st.line_chart(data)
50
```
51

52
### Container Functions
53

54
Generic container functions for grouping content with optional styling and behavior.
55

56
```python { .api }
57
def container(*, height=None, border=None):
58
    """
59
    Create generic container for grouping content with optional styling.
60

61
    Args:
62
        height (int, optional): Container height in pixels
63
        border (bool, optional): Whether to show container border
64

65
    Returns:
66
        DeltaGenerator: Container context manager
67
    """
68

69
def empty():
70
    """
71
    Create placeholder container that can be filled later.
72

73
    Returns:
74
        DeltaGenerator: Empty placeholder container
75
    """
76
```
77

78
Example usage:
79
```python
80
# Create bordered container
81
with st.container(border=True):
82
    st.write("Content inside bordered container")
83

84
# Create placeholder for later use
85
placeholder = st.empty()
86
# Later fill the placeholder
87
placeholder.write("Dynamic content")
88
```
89

90
### Expandable Containers
91

92
Collapsible containers for organizing content that can be shown or hidden.
93

94
```python { .api }
95
def expander(label, *, expanded=False, icon=None):
96
    """
97
    Create expandable/collapsible container with toggle functionality.
98

99
    Args:
100
        label (str): Expander header text
101
        expanded (bool): Whether to start in expanded state
102
        icon (str, optional): Icon name or emoji for header
103

104
    Returns:
105
        DeltaGenerator: Expandable container context manager
106
    """
107

108
def popover(label, *, help=None, disabled=False, use_container_width=False, icon=None):
109
    """
110
    Create popover container that opens on button click.
111

112
    Args:
113
        label (str): Popover button text
114
        help (str, optional): Tooltip text for button
115
        disabled (bool): Whether popover button is disabled
116
        use_container_width (bool): Whether button uses full container width
117
        icon (str, optional): Icon name or emoji for button
118

119
    Returns:
120
        DeltaGenerator: Popover container context manager
121
    """
122
```
123

124
Example usage:
125
```python
126
# Create expander
127
with st.expander("Show details", expanded=False):
128
    st.write("Detailed information here")
129

130
# Create popover
131
with st.popover("Options"):
132
    st.write("Popover content")
133
    option = st.selectbox("Choose:", ["A", "B", "C"])
134
```
135

136
### Sidebar
137

138
Dedicated sidebar container for navigation and secondary content.
139

140
```python { .api }
141
sidebar: DeltaGenerator
142
```
143

144
The sidebar object provides access to the sidebar container where you can place widgets and content that appears in a collapsible side panel.
145

146
Example usage:
147
```python
148
# Add content to sidebar
149
st.sidebar.title("Navigation")
150
st.sidebar.selectbox("Choose page:", ["Home", "About", "Contact"])
151

152
# Sidebar can contain any widget or display element
153
with st.sidebar:
154
    st.write("Sidebar content")
155
    user_input = st.text_input("Enter value:")
156
```
157

158
### Status and Progress Elements
159

160
Containers and widgets for showing status, progress, and temporary states.
161

162
```python { .api }
163
def status(label, *, expanded=False, state="running"):
164
    """
165
    Create status container that shows operation progress with state indicator.
166

167
    Args:
168
        label (str): Status label/description
169
        expanded (bool): Whether to show details by default
170
        state (str): Status state ("running", "complete", "error")
171

172
    Returns:
173
        DeltaGenerator: Status container context manager
174
    """
175

176
def progress(value, *, text=None, help=None):
177
    """
178
    Display progress bar with optional text label.
179

180
    Args:
181
        value (float): Progress value between 0.0 and 1.0
182
        text (str, optional): Text label for progress bar
183
        help (str, optional): Tooltip text
184

185
    Returns:
186
        DeltaGenerator: Progress bar element that can be updated
187
    """
188

189
def spinner(text=""):
190
    """
191
    Display loading spinner with optional text during long operations.
192

193
    Args:
194
        text (str): Loading message text
195

196
    Returns:
197
        ContextManager: Spinner context manager for use with 'with' statement
198
    """
199
```
200

201
Example usage:
202
```python
203
# Status container
204
with st.status("Processing data...", expanded=True):
205
    st.write("Loading dataset")
206
    # ... processing code ...
207
    st.write("Analysis complete")
208

209
# Progress bar
210
progress_bar = st.progress(0, text="Starting...")
211
for i in range(100):
212
    progress_bar.progress(i + 1, text=f"Processing {i+1}/100")
213

214
# Spinner for long operations
215
with st.spinner("Loading..."):
216
    time.sleep(5)  # Long operation
217
st.success("Done!")
218
```
219

220
### Message and Alert Containers
221

222
Containers for displaying status messages, alerts, and notifications.
223

224
```python { .api }
225
def success(body, *, icon=None, help=None):
226
    """
227
    Display success message with green styling.
228

229
    Args:
230
        body (str): Success message text
231
        icon (str, optional): Custom icon (default checkmark)
232
        help (str, optional): Tooltip text
233
    """
234

235
def info(body, *, icon=None, help=None):
236
    """
237
    Display informational message with blue styling.
238

239
    Args:
240
        body (str): Info message text
241
        icon (str, optional): Custom icon (default info icon)
242
        help (str, optional): Tooltip text
243
    """
244

245
def warning(body, *, icon=None, help=None):
246
    """
247
    Display warning message with yellow styling.
248

249
    Args:
250
        body (str): Warning message text
251
        icon (str, optional): Custom icon (default warning icon)
252
        help (str, optional): Tooltip text
253
    """
254

255
def error(body, *, icon=None, help=None):
256
    """
257
    Display error message with red styling.
258

259
    Args:
260
        body (str): Error message text
261
        icon (str, optional): Custom icon (default error icon)
262
        help (str, optional): Tooltip text
263
    """
264

265
def exception(exception, *, help=None):
266
    """
267
    Display formatted exception with traceback information.
268

269
    Args:
270
        exception (Exception): Exception object to display
271
        help (str, optional): Tooltip text
272
    """
273

274
def toast(body, *, icon=None, duration="short"):
275
    """
276
    Display temporary toast notification that auto-dismisses.
277

278
    Args:
279
        body (str): Toast message text
280
        icon (str, optional): Icon name or emoji
281
        duration (str or int, optional): How long to show toast ("short", "long", "infinite", or seconds)
282
    """
283
```
284

285
Example usage:
286
```python
287
# Message containers
288
st.success("Operation completed successfully!")
289
st.info("This is informational content")
290
st.warning("Please review your input")
291
st.error("An error occurred")
292

293
# Exception display
294
try:
295
    risky_operation()
296
except Exception as e:
297
    st.exception(e)
298

299
# Toast notification
300
st.toast("File saved!", icon="✅")
301
```
302

303
### Animation and Visual Effects
304

305
Functions for adding visual flair and celebratory effects.
306

307
```python { .api }
308
def balloons():
309
    """Display floating balloons animation for celebration."""
310

311
def snow():
312
    """Display falling snow animation for celebration."""
313
```
314

315
Example usage:
316
```python
317
# Celebratory animations
318
if user_completed_task:
319
    st.balloons()  # Show balloons
320

321
if holiday_theme:
322
    st.snow()  # Show snow effect
323
```
324

325
### Layout Patterns
326

327
Common layout patterns and best practices:
328

329
#### Multi-Column Layouts
330
```python
331
# Equal columns
332
col1, col2, col3 = st.columns(3)
333

334
# Custom column widths
335
col1, col2 = st.columns([3, 1])  # 3:1 ratio
336

337
# With gap control
338
col1, col2 = st.columns(2, gap="large")
339
```
340

341
#### Nested Containers
342
```python
343
# Container within container
344
with st.container(border=True):
345
    col1, col2 = st.columns(2)
346
    with col1:
347
        with st.expander("Details"):
348
            st.write("Nested content")
349
```
350

351
#### Sidebar Layout
352
```python
353
# Sidebar with main content
354
with st.sidebar:
355
    page = st.selectbox("Navigate:", ["Home", "Data", "Settings"])
356

357
# Main content area
358
if page == "Home":
359
    st.title("Welcome")
360
elif page == "Data":
361
    st.dataframe(data)
362
```
363

364
#### Form Layout
365
```python
366
# Form with organized layout
367
with st.form("user_form"):
368
    col1, col2 = st.columns(2)
369
    with col1:
370
        name = st.text_input("Name")
371
        email = st.text_input("Email")
372
    with col2:
373
        age = st.number_input("Age", min_value=0)
374
        country = st.selectbox("Country", countries)
375

376
    submitted = st.form_submit_button("Submit")
377
```
378

379
#### Tab Organization
380
```python
381
# Tabbed interface
382
tab1, tab2, tab3 = st.tabs(["Overview", "Details", "Settings"])
383

384
with tab1:
385
    st.metric("Users", 1234)
386
    st.line_chart(overview_data)
387

388
with tab2:
389
    st.dataframe(detailed_data)
390

391
with tab3:
392
    settings = st.form("settings_form")
393
```