File Browser

marimo.ui.file_browser

file_browser(
    initial_path: str = "",
    filetypes: Optional[Sequence[str]] = None,
    selection_mode: str = "file",
    multiple: bool = True,
    restrict_navigation: bool = False,
    *,
    label: str = "",
    on_change: Optional[
        Callable[[Sequence[FileInfo]], None]
    ] = None
)

Bases: UIElement[List[Dict[str, Any]], Sequence[FileInfo]]

File browser for browsing and selecting server-side files.

Examples:

Selecting multiple files:

file_browser = mo.ui.file_browser(
    initial_path="path/to/dir", multiple=True
)

# Access the selected file path(s):
file_browser.path(index)

# Get name of selected file(s)
file_browser.name(index)

ATTRIBUTE	DESCRIPTION
value	A sequence of file paths representing selected files. TYPE: Sequence[FileInfo]

PARAMETER	DESCRIPTION
initial_path	Starting directory. Defaults to current working directory. TYPE: str DEFAULT: ''
filetypes	The file types to display in each directory; for example, filetypes=[".txt", ".csv"]. If None, all files are displayed. Defaults to None. TYPE: Sequence[str] DEFAULT: None
selection_mode	Either "file" or "directory". Defaults to "file". TYPE: str DEFAULT: 'file'
multiple	If True, allow the user to select multiple files. Defaults to True. TYPE: bool DEFAULT: True
restrict_navigation	If True, prevent the user from navigating any level above the given path. Defaults to False. TYPE: bool DEFAULT: False
label	Markdown label for the element. Defaults to "". TYPE: str DEFAULT: ''
on_change	Optional callback to run when this element's value changes. Defaults to None. TYPE: Callable[[Sequence[FileInfo]], None] DEFAULT: None

filetypes instance-attribute

filetypes = filetypes

initial_path instance-attribute

initial_path = initial_path

restrict_navigation instance-attribute

restrict_navigation = restrict_navigation

selection_mode instance-attribute

selection_mode = selection_mode

text property

text: str

A string of HTML representing this element.

value property writable

value: T

The element's current value.

batch

batch(**elements: UIElement[JSONType, object]) -> batch

Convert an HTML object with templated text into a UI element.

This method lets you create custom UI elements that are represented by arbitrary HTML.

Example.

user_info = mo.md(
    '''
    - What's your name?: {name}
    - When were you born?: {birthday}
    '''
).batch(name=mo.ui.text(), birthday=mo.ui.date())

In this example, user_info is a UI Element whose output is markdown and whose value is a dict with keys 'name' and 'birthday' (and values equal to the values of their corresponding elements).

Args.

• elements: the UI elements to interpolate into the HTML template.

callout

callout(
    kind: Literal[
        "neutral", "danger", "warn", "success", "info"
    ] = "neutral"
) -> Html

Create a callout containing this HTML element.

A callout wraps your HTML element in a raised box, emphasizing its importance. You can style the callout for different situations with the kind argument.

Examples.

mo.md("Hooray, you did it!").callout(kind="success")

mo.md("It's dangerous to go alone!").callout(kind="warn")

center

center() -> Html

Center an item.

Example.

mo.md("# Hello, world").center()

Returns.

An Html object.

form

form(
    label: str = "",
    *,
    bordered: bool = True,
    loading: bool = False,
    submit_button_label: str = "Submit",
    submit_button_tooltip: Optional[str] = None,
    submit_button_disabled: bool = False,
    clear_on_submit: bool = False,
    show_clear_button: bool = False,
    clear_button_label: str = "Clear",
    clear_button_tooltip: Optional[str] = None,
    validate: Optional[
        Callable[[Optional[JSONType]], Optional[str]]
    ] = None,
    on_change: Optional[
        Callable[[Optional[T]], None]
    ] = None
) -> form[S, T]

Create a submittable form out of this UIElement.

Use this method to create a form that gates the submission of a UIElements value until a submit button is clicked.

The value of the form is the value of the underlying element the last time the form was submitted.

Examples.

Convert any UIElement into a form:

prompt = mo.ui.text_area().form()

Combine with HTML.batch to create a form made out of multiple UIElements:

form = (
    mo.ui.md(
        '''
    **Enter your prompt.**

    {prompt}

    **Choose a random seed.**

    {seed}
    '''
    )
    .batch(
        prompt=mo.ui.text_area(),
        seed=mo.ui.number(),
    )
    .form()
)

Args.

• label: A text label for the form.
• bordered: whether the form should have a border
• loading: whether the form should be in a loading state
• submit_button_label: the label of the submit button
• submit_button_tooltip: the tooltip of the submit button
• submit_button_disabled: whether the submit button should be disabled
• clear_on_submit: whether the form should clear its contents after submitting
• show_clear_button: whether the form should show a clear button
• clear_button_label: the label of the clear button
• clear_button_tooltip: the tooltip of the clear button
• validate: a function that takes the form's value and returns an error message if the value is invalid, or None if the value is valid

left

left() -> Html

Left-justify.

Example.

mo.md("# Hello, world").left()

Returns.

An Html object.

list_directory

list_directory(
    args: ListDirectoryArgs,
) -> ListDirectoryResponse

name

name(index: int = 0) -> Optional[str]

Get file name at index.

PARAMETER	DESCRIPTION
index	Index of the file to get the name from. Defaults to 0. TYPE: int DEFAULT: 0

RETURNS	DESCRIPTION
Optional[str]	Optional[str]: The name of the file at the specified index, or None if index is out of range.

path

path(index: int = 0) -> Optional[str]

Get file path at index.

PARAMETER	DESCRIPTION
index	Index of the file to get the path from. Defaults to 0. TYPE: int DEFAULT: 0

RETURNS	DESCRIPTION
Optional[str]	Optional[str]: The path of the file at the specified index, or None if index is out of range.

right

right() -> Html

Right-justify.

Example.

mo.md("# Hello, world").right()

Returns.

An Html object.

send_message

send_message(
    message: Dict[str, object],
    buffers: Optional[Sequence[bytes]],
) -> None

Send a message to the element rendered on the frontend from the backend.

style

style(
    style: Optional[dict[str, Any]] = None, **kwargs: Any
) -> Html

Wrap an object in a styled container.

Example.

mo.md("...").style({"max-height": "300px", "overflow": "auto"})
mo.md("...").style(max_height="300px", overflow="auto")

Args.

• style: an optional dict of CSS styles, keyed by property name
• **kwargs: CSS styles as keyword arguments