streamlit-elements

All elements must be rendered within an elements() context manager. The elements() function takes a unique key as a parameter which cannot be reused by another frame or Streamlit widget.

Creating elements with children

You can add children to an element by passing them as arguments or by using a with statement.

from streamlit_elements import elements, mui, html

with elements("my_frame"):
    # Single child
    mui.Typography("Hello world")

    # Multiple children as arguments
    mui.Button(
        mui.icon.EmojiPeople,
        mui.icon.DoubleArrow,
        "Button with multiple children"
    )

    # Multiple children using 'with' statement
    with mui.Button:
        mui.icon.EmojiPeople()
        mui.icon.DoubleArrow()
        mui.Typography("Button with multiple children")

    # Nested children
    with mui.Paper:
        with mui.Typography:
            html.p("Hello world")
            html.p("Goodbye world")

Retrieve element data manually

You can define a function to handle events (like onChange) and update st.session_state manually.

Synchronize with sync()

Use sync("key") to automatically store event data into a session state item. If an event passes multiple parameters, use sync("param1", "param2"). To ignore the first parameter but keep others, use sync(None, "param2").

Defer reloads with lazy()

To prevent the entire Streamlit app from reloading on every single input (e.g., every keystroke in a text field), wrap your callback with lazy(). This defers the execution until a non-lazy callback is triggered.

import streamlit as st
from streamlit_elements import elements, mui, sync, lazy

with elements("callbacks"):
    if "my_event" not in st.session_state:
        st.session_state.my_event = None

    # 1. Manual callback
    def handle_change(event):
        st.session_state.my_text = event.target.value

    mui.TextField(label="Manual", onChange=handle_change)

    # 2. Using sync()
    mui.TextField(label="Sync", onChange=sync("my_event"))

    # 3. Using lazy() to avoid constant reloads
    # This will only sync when a non-lazy callback (like a button) is clicked
    mui.TextField(label="Lazy Sync", onChange=lazy(sync("my_event")))
    mui.Button("Update", onClick=sync())

Adding properties

Elements accept properties via named parameters. If a parameter name is a Python keyword (like in), append an underscore (e.g., in_=True).

Applying custom CSS

• Material UI elements: Use the sx property for styling.
• Other elements (like HTML): Use the css property (based on Emotion).

from streamlit_elements import elements, mui, html

with elements("styling"):
    # Using properties and sx for MUI
    with mui.Paper(elevation=3, variant="outlined", square=True):
        mui.TextField(
            label="My text input",
            defaultValue="Type here",
            variant="outlined",
        )

    # Using sx for MUI Box
    mui.Box(
        "Some text in a styled box",
        sx={
            "bgcolor": "background.paper",
            "boxShadow": 1,
            "borderRadius": 2,
            "p": 2,
            "minWidth": 300,
        }
    )

    # Using css for HTML elements
    html.div(
        "This has a hotpink background",
        css={
            "backgroundColor": "hotpink",
            "&:hover": {
                "color": "lightgreen"
            }
        }
    )