TextInput

The TextInput widget displays a text input field. It is useful for entering names, labels, filters, search queries, or any short text values in your Mercury App. By default it is a single-line input; set rows to a value greater than 1 to get a multi-line textarea.

Live Demo

You can try the TextInput widget directly in this interactive example:

🚀 Load interactive demo Hover to start

Usage

To create a TextInput widget, provide a label. The current text entered by the user is always available via .value.

Basic Example

Code

import mercury as mr

text = mr.TextInput(
    label="Enter your name"
)

To get the current value:

text.value

Default Value

You can provide an initial value using the value argument.

Code

text = mr.TextInput(
    label="City",
    value="Warsaw"
)

text.value

Output

Warsaw

Multi-line Text

Set rows to a value greater than 1 to render the widget as a resizable textarea.

Code

notes = mr.TextInput(
    label="Notes",
    rows=5
)

notes.value

Layout

Use the position argument to control where the widget is displayed. The default is position="sidebar".

Available positions:

"sidebar" — displayed in the left sidebar (default)
"inline" — displayed in the main notebook output
"bottom" — displayed after all notebook cells

Code

mr.TextInput(
    label="Search",
    position="inline"
)

TextInput Props

label

type: string

Text displayed above the input field. The default is "Enter text".

value

type: string

Initial text value.

If omitted, defaults to an empty string.
The value always reflects the current text entered by the user.

url_key

type: string

Name of the URL query parameter used to override the initial value.

If the URL contains a non-empty value for this key, it takes precedence over value.
Missing, empty, or whitespace-only URL values fall back to value.

Example:

?username=jan

position

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

Controls where the widget is rendered:

sidebar — in the sidebar (default)
inline — directly in the notebook cell output
bottom — after all notebook cells

disabled

type: bool

If True, the input is visible but cannot be edited. The default is False.

hidden

type: bool

If True, the widget exists in the UI state but is not rendered. The default is False.

rows

type: int

Number of visible text rows. The default is 1.

rows=1 renders a single-line input field.
rows greater than 1 renders a resizable textarea with that many visible lines.

key

type: string

Unique identifier used to distinguish widgets with identical arguments.

Notes

The widget value is always available via .value.
Changes are debounced slightly to avoid excessive updates.
url_key can be used to initialize the widget from URL query parameters.
Empty or whitespace-only URL values are ignored.
For longer text, set rows to a value greater than 1 to get a resizable textarea.