File Browser¶

marimo.ui.file_browser ¶

file_browser(initial_path: Union[str, Path] = '', filetypes: Optional[Sequence[str]] = None, selection_mode: Literal['file', 'directory'] = 'file', multiple: bool = True, restrict_navigation: bool = False, *, limit: int = 50, label: str = '', on_change: Optional[Callable[[Sequence[FileBrowserFileInfo]], None]] = None)

Bases: UIElement[list[TypedFileBrowserFileInfo], Sequence[FileBrowserFileInfo]]

File browser for browsing and selecting server-side files. This element supports local files, S3, GCS, and Azure.

Examples:

Selecting multiple files:

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

# Access the selected file path(s):
file_browser.path(index=0)  # returns a Path object

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

Connecting to an S3 (or GCS, Azure) bucket:

from cloudpathlib import S3Path

file_browser = mo.ui.file_browser(
    initial_path=S3Path("s3://my-bucket/folder/")
)

# Access the selected file path(s):
file_browser.path(index=0)  # returns a S3Path object

# Read the contents of the selected file(s):
file_browser.path(index=0).read_text()

Using with client credentials:

from cloudpathlib import GSClient, GSPath

# Create a client with credentials
gs_client = GSClient("storage_credentials.json", project="my-project")

# Create a path with the client
cloudpath = GSPath("gs://my-bucket/folder", client=gs_client)

# Use the path with file_browser
file_browser = mo.ui.file_browser(initial_path=cloudpath)

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. If a string, it will be interpreted as a local path. If a Path, it will be interpreted as a local path. If a CloudPath (from cloudpathlib), such as S3Path, GCSPath, or AzurePath, files will be loaded from the respective cloud storage bucket. If a CloudPath with a client is provided, that client will be used for all operations. TYPE: `Union[str, Path, AnyPath]` 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: `Literal['file', 'directory']` 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`
`limit`	Maximum number of files to display. Defaults to 50. TYPE: `int` DEFAULT: `50`
`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`

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).

PARAMETER	DESCRIPTION
`elements`	the UI elements to interpolate into the HTML template. TYPE: `UIElement[JSONType, object]` DEFAULT: `{}`

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	DESCRIPTION
`Html`	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.

Creates a form that gates submission of a UIElement's value until a submit button is clicked. The form's value is the value of the underlying element from the last submission.

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()
)

PARAMETER	DESCRIPTION
`label`	A text label for the form. TYPE: `str` DEFAULT: `''`
`bordered`	Whether the form should have a border. TYPE: `bool` DEFAULT: `True`
`loading`	Whether the form should be in a loading state. TYPE: `bool` DEFAULT: `False`
`submit_button_label`	The label of the submit button. TYPE: `str` DEFAULT: `'Submit'`
`submit_button_tooltip`	The tooltip of the submit button. TYPE: `Optional[str]` DEFAULT: `None`
`submit_button_disabled`	Whether the submit button should be disabled. TYPE: `bool` DEFAULT: `False`
`clear_on_submit`	Whether the form should clear its contents after submitting. TYPE: `bool` DEFAULT: `False`
`show_clear_button`	Whether the form should show a clear button. TYPE: `bool` DEFAULT: `False`
`clear_button_label`	The label of the clear button. TYPE: `str` DEFAULT: `'Clear'`
`clear_button_tooltip`	The tooltip of the clear button. TYPE: `Optional[str]` DEFAULT: `None`
`validate`	A function that takes the form's value and returns an error message if invalid, or `None` if valid. TYPE: `Optional[Callable[[Optional[JSONType]], Optional[str]]]` DEFAULT: `None`
`on_change`	Optional callback to run when this element's value changes. Defaults to None. TYPE: `Optional[Callable[[Optional[T]], None]]` DEFAULT: `None`

left ¶

left() -> Html

Left-justify.

Example

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

RETURNS	DESCRIPTION
`Html`	An `Html` object.

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[Path]

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[Path]`	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	DESCRIPTION
`Html`	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")

PARAMETER	DESCRIPTION
`style`	an optional dict of CSS styles, keyed by property name TYPE: `Optional[dict[str, Any]]` DEFAULT: `None`
`**kwargs`	CSS styles as keyword arguments TYPE: `Any` DEFAULT: `{}`

File Browser¶

marimo.ui.file_browser ¶

text property ¶

value property writable ¶

batch ¶

callout ¶

center ¶

form ¶

left ¶

name ¶

path ¶

right ¶

send_message ¶

style ¶

text `property` ¶

value `property` `writable` ¶