Download

The Download widget renders a button that lets users download data generated inside a Mercury App.
It is useful for exporting results, reports, CSV files, model artifacts, or any other content produced during notebook execution.

The widget works entirely in the browser by creating a temporary file (Blob) and triggering a download when the button is clicked.

Basic Usage

Download a Text File

import mercury as mr

mr.Download(
    data="Hello world!\nThis file was generated by Mercury.",
    filename="hello.txt",
    label="Download TXT"
)

Clicking the button downloads a file named hello.txt.

Download Common File Types

CSV

import mercury as mr

csv_data = "a,b\n1,2\n3,4\n"

mr.Download(
    data=csv_data,
    filename="data.csv",
    mime="text/csv",
    label="Download CSV"
)

JSON

import json
import mercury as mr

payload = {"a": 1, "b": [1, 2, 3]}

mr.Download(
    data=json.dumps(payload, indent=2),
    filename="data.json",
    mime="application/json",
    label="Download JSON"
)

Download a pandas DataFrame

import pandas as pd
import mercury as mr

df = pd.DataFrame({
    "name": ["Alice", "Bob", "Charlie"],
    "score": [82, 91, 77]
})

csv_data = df.to_csv(index=False)

mr.Download(
    data=csv_data,
    filename="scores.csv",
    mime="text/csv",
    label="Download CSV"
)

Binary Files (Base64)

For binary data (images, models, zip files), encode the content as base64 and set is_base64=True.

import base64
import mercury as mr

raw_bytes = b"\x00\x01\x02\x03"
b64 = base64.b64encode(raw_bytes).decode("ascii")

mr.Download(
    data=b64,
    filename="data.bin",
    mime="application/octet-stream",
    is_base64=True,
    label="Download binary"
)

Note

When is_base64=True, decoding happens in the browser before the download starts.

---

Layout

Use position to control where the download button is displayed:

• "sidebar" — place the button in the sidebar (default)
• "inline" — render it in the notebook output flow
• "bottom" — render it after all notebook cells

import mercury as mr

mr.Download(
    data="Report content",
    filename="report.txt",
    position="bottom"
)

---

Download Props

data (required)

type: string | bytes

Content of the file.

• Plain text by default
• Base64-encoded string if is_base64=True

---

filename

type: string

Name of the downloaded file.

Default: "file.txt"

---

label

type: string

Text displayed on the download button.

Default: "Download"

---

mime

type: string

MIME type of the file.

Default: "text/plain"

---

is_base64

type: bool

If True, data is treated as base64-encoded content.

Default: False

---

position

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

Controls where the widget is rendered.

Default: "sidebar"

---

key

type: string

Unique identifier used to reuse the same widget instance.

---

Notes

• Download renders immediately and does not require user interaction until the button is clicked.
• Large files may increase browser memory usage since data is held in memory.
• The widget works fully client-side; no server storage is involved.