pypi-streamlit

1
# Layout and Containers
2

3
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.
4

5
## Capabilities
6

7
### Layout Functions
8

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

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

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

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

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

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

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

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

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

53
### Container Functions
54

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

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

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

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

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

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

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

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

91
### Expandable Containers
92

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

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

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

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

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

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

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

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

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

137
### Sidebar
138

139
Dedicated sidebar container for navigation and secondary content.
140

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

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

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

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

159
### Status and Progress Elements
160

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

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

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

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

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

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

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

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

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

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

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

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

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

221
### Message and Alert Containers
222

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

304
### Animation and Visual Effects
305

306
Functions for adding visual flair and celebratory effects.
307

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

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

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

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

326
### Layout Patterns
327

328
Common layout patterns and best practices:
329

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

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

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

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

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

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

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

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

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

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

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

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