Columns

The Columns helper lets you create a responsive row of output areas (columns) inside a Mercury App. It is useful for building dashboards, side-by-side comparisons, charts grids, or multi-panel layouts.

Each column is returned as an Output widget, so you can write into it using a with block. On rerun, reused column outputs are cleared by default so the layout shows the latest execution result.

Live Demo

You can check the Columns widget directly in this interactive example:

🚀 Load interactive demo Hover to start

🛠️ Source code ⛅ Open demo in new tab

Usage

Call mr.Columns() to create a row of columns. The function returns a tuple of output widgets — one for each column. Columns are responsive by default: they stay side by side while each column has comfortable space and automatically stack as their containing area gets narrower.

Basic Example

Code

import mercury as mr

col1, col2 = mr.Columns(2)

with col1:
    print("Left column")

with col2:
    print("Right column")

Three Columns

Code

c1, c2, c3 = mr.Columns(3)

with c1:
    print("Column 1")

with c2:
    print("Column 2")

with c3:
    print("Column 3")

Proportional Widths

Pass a list of positive numbers to create columns with proportional widths. For example, [0.4, 0.6] creates two columns where the first takes about 40% and the second takes about 60% of the available row space.

Code

left, right = mr.Columns([0.4, 0.6])

with left:
    print("40% column")

with right:
    print("60% column")

The values are treated as ratios, so [40, 60], [0.4, 0.6], and [2, 3] all work.

Minimum Width and Responsiveness

No responsive configuration is required. By default, each column targets a minimum width of 260px. Two columns therefore stay in one row on desktop and tablet layouts, then stack into two rows on a typical mobile screen. Four columns can progressively wrap from four to two to one per row as their containing area gets narrower.

Responsiveness is based on the available container width, so it also works for nested layouts and pages with a sidebar.

Use min_width only when you want columns to wrap earlier or allow a denser layout.

Code

c1, c2, c3 = mr.Columns(
    n=3,
    min_width="320px"
)

Gap Between Columns

Control spacing between columns using the gap argument.

Code

c1, c2 = mr.Columns(
    n=2,
    gap="32px"
)

Borders

You can control column borders explicitly or let the theme decide.

Examples

# Theme-based borders (default)
mr.Columns(2)

# Custom border
mr.Columns(2, border="1px solid lightgray")

# No borders
mr.Columns(2, border="")

Layout Position

Use the position argument to control where the columns are displayed. The default is position="inline".

Available positions:

• "sidebar" — display columns in the sidebar
• "inline" — display columns in the main notebook output (default)
• "bottom" — display columns after all notebook cells

Code

mr.Columns(
    n=2,
    position="bottom"
)

Append Previous Content

By default, append=False, so content from the previous run is cleared before new content is written. Set append=True when you intentionally want to keep previous output and append new content on each run.

Code

col1, col2 = mr.Columns(2, append=True)

with col1:
    print("This output is appended on each run")

Clear Content Manually

Each returned column is an output widget and supports .clear(). Use it when you want to clear a column manually from your notebook code.

Code

col1, col2 = mr.Columns(2)

col1.clear()

with col1:
    print("Fresh content")

Columns Props

n

type: int | list[float]

Number of equal-width columns, or a list of proportional widths.

Examples:

• 2 — two equal-width columns
• [0.4, 0.6] — two columns with a 40/60 width ratio
• [1, 2, 1] — three columns with a 1/2/1 width ratio

Integer values must be at least 1. Width-list values must be positive numbers.

---

min_width

type: string

Minimum width of each column (CSS value). The default targets 260px without allowing a column to overflow a narrower parent.

Examples:

• "120px"
• "240px"

---

gap

type: string

Gap between columns (CSS value).

Examples:

• "8px"
• "16px"
• "32px"

---

border

type: string | None

Controls column borders:

• None — use theme defaults
• "" — disable borders
• CSS string — custom border (e.g. "1px solid red")

---

position

type: "sidebar" | "inline" | "bottom"

Controls where the columns are rendered.

---

key

type: string

Unique identifier used to distinguish widgets with identical arguments.

Note

If the same code cell is run again, Mercury reuses the previous Columns instance unless a different key is specified.

The key value is required when Columns are created inside loops.

---

append

type: bool

Controls what happens when Mercury reuses the same Columns instance:

• False — clear previous column content before writing new content (default)
• True — keep previous content and append new output

---

Notes

• Columns are responsive and automatically wrap when space is limited.
• Each returned object is an Output widget with a .clear() method.
• Use with column: blocks to write content into columns.
• By default, reruns replace previous column content. Use append=True to accumulate content.
• Columns are ideal for charts, tables, metrics, or grouped controls.