Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 38 ยท Layout and Navigation

Columns and Containers

Lay out a Streamlit page with st.columns, st.container and st.empty. Learn column ratios, gaps, alignment, bordered cards, scrolling containers and drawing out of order.

Without layout calls, Streamlit stacks everything in one tall column, in the order of your script. That is fine for a first prototype, but dashboards need metric cards side by side, a chart next to a table, and sometimes a block you fill in later. Three tools do most of the work: st.columns (horizontal split), st.container (a grouping box) and st.empty (a single replaceable slot).

The Streamlit code is real and read-only; the page it creates is described in words. Runnable stand-ins calculate column widths and show the "fill in later" idea.

st.columns

Python
import streamlit as st

left, middle, right = st.columns(3)

left.metric("Revenue", "$12,480", "$850")
middle.metric("Orders", "312", "-14")
with right:
    st.metric("Customers", "1,204", "+36")
    st.caption("Updated 5 min ago")

st.columns(3) returns three column objects of equal width. The page shows three side-by-side blocks, each with a metric card; the right one also shows a small caption. There are two ways to put content in a column: call methods on the column (left.metric(...)), or use with right: so every st. call inside lands in that column. Both are equivalent.

Column widths

Pass a list of relative widths instead of a count:

Python
wide, narrow = st.columns([3, 1])

This makes the first column three times as wide as the second (75% and 25% of the width). The numbers are proportions, not pixels, so [2, 1] and [6, 3] are identical.

Argument Values Effect
spec int or list of numbers Number of columns or their relative widths
gap "small", "medium" (default), "large" Space between columns
vertical_alignment "top", "center", "bottom" Align content when columns have different heights
border=True bool Draw a border around each column (card style)

Computing proportions (runnable stand-in)

The block below calculates the width each column would get from a spec list, which is a quick way to think about ratios. It is plain arithmetic, not a Streamlit call.

Python Stand-in: what share does each column get?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Columns on small screens

On a narrow screen (a phone), Streamlit stacks columns vertically so everything stays readable. Do not rely on columns for tight tables of numbers; use st.dataframe for those. Also avoid many columns: more than four or five make each one too narrow to read.

Nesting

You can put columns inside a column, but Streamlit limits how deeply layouts can nest, and deep nesting is hard to read on a narrow screen anyway. If you need more structure, use a bordered container or tabs, described in the next lesson.

A grid of cards from data

A common task is to loop over data and make one card per item. Combine st.columns with zip or enumerate:

Python
items = [("Tea", 120), ("Coffee", 310), ("Juice", 80), ("Water", 150),
         ("Soda", 95), ("Milk", 60)]

per_row = 3
for start in range(0, len(items), per_row):
    row = st.columns(per_row)
    for col, (name, units) in zip(row, items[start:start + per_row]):
        col.metric(name, units, border=True)

The page shows two rows of three metric cards. Notice that a new st.columns call is made for each row, so the rows line up.

The row-chunking logic is plain Python. Try it with an uneven count to see the last row:

Python Split items into rows of three

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

With seven items the last row has one card. In the app, you would call st.columns(per_row) and zip the row with the chunk; zip stops at the shorter list, so the unused columns stay empty.

st.container

A container is an invisible (or bordered) box that groups elements. It matters for three reasons.

1. Grouping with a border:

Python
with st.container(border=True):
    st.subheader("Summary")
    st.write("Revenue grew 6.8% this week.")

The page shows a box with a thin border around a subheading and a sentence, a "card".

2. Scrolling areas: st.container(height=200) makes a fixed-height box with a scrollbar when its content is taller, which is useful for logs or long lists, and for chat message areas.

3. Drawing out of order. The script runs top to bottom, but a container is a reserved position on the page that you can fill whenever you like:

Python
import streamlit as st

header = st.container()          # reserves a spot at the top
body = st.container()

with body:
    result = sum(range(1_000_000))      # slow work first
    st.write("Result:", result)

with header:
    st.title("Report")                  # appears ABOVE the body anyway
    st.caption(f"The answer has {len(str(result))} digits.")

The page shows the title and caption first and the result below, even though the code wrote the body first. This is how an app puts a summary at the top that depends on a calculation lower down.

Placing elements out of order (stand-in)

The block below is not Streamlit. It simulates containers as named slots to show that the page order is set by where the slots are created, not by when you fill them.

Python Stand-in: containers reserve positions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

st.empty: one replaceable slot

st.empty() creates a single-element placeholder. Whatever you put in it replaces what was there, and placeholder.empty() clears it. It is the tool for live-updating a value in a loop:

Python
import time
import streamlit as st

slot = st.empty()
for second in range(3, 0, -1):
    slot.metric("Starting in", second)
    time.sleep(1)
slot.success("Go!")

The page shows a metric reading 3, then 2, then 1 in the same place, and finally a green "Go!" box replaces it. A normal st.write in a loop would add a new line each time instead. (While the loop runs, the script is busy, so other widgets cannot be used; for long-running updates look at fragments in a later chapter.)

Designing a page

A typical dashboard layout

Top row Metric columns
Middle Chart beside a table
Bottom Details in a container
1 / 2

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does st.columns([3, 1]) create?

    The list holds relative widths, so the columns get 75% and 25% of the width.
  2. 2. How do you add content to a column called right?

    Methods on the column object and a with block are equivalent.
  3. 3. Why can a container be used to put a summary above a slow calculation?

    Elements appear where the container was created, not where you write into it.
  4. 4. What does st.empty() give you?

    It is a placeholder for one element at a time, ideal for updating values in a loop.

Summary

  • st.columns splits the page horizontally; pass a count or relative widths, and use border, gap and vertical_alignment to style them.
  • Use with column: or column.method() to place content.
  • st.container groups content, makes cards and scrolling boxes, and lets you draw out of order.
  • st.empty is a single replaceable slot for live updates.

Next: Tabs, Expanders, Popovers and Dialogs