Streamlit Floating Container

A Streamlit custom component that creates a floating, draggable panel overlay for your Streamlit applications. Perfect for adding chat interfaces, FAQ sections, or any content that needs to be accessible without leaving the current page.

Features

• Floating Panel — a glassmorphic floating panel that hovers over your Streamlit app
• Draggable — vertical drag handle to reposition the panel button anywhere on the screen
• Expandable — toggle the panel to nearly full viewport height
• Start Position — configure the initial button position (top, middle, or bottom)
• Auto-pinned Chat Input — st.chat_input placed directly inside the container automatically sticks to the bottom, mimicking Streamlit's native chat layout
• Customizable — Material icon support, optional label, and glassmorphic toggle
• Theme Integration — automatically adapts to your Streamlit theme colors
• Resilient to reruns — component hot-updates in place from props; DOM state survives Streamlit reruns without reload hacks

Installation

pip install streamlit-floating-container

Using UV:

uv add streamlit-floating-container

Usage

import streamlit as st
from streamlit_floating_container import FloatingContainer

st.set_page_config(layout="wide")
st.title("My App")

fp = FloatingContainer(
    icon=":material/chat:",
    label="Help",
    start_position="top",
    key="my_float",
    glassmorphic=True,
)

with fp.panel():
    st.subheader("FAQ", anchor=False)
    st.write("Your content here...")

Chat Example

Place st.chat_input directly inside the container — the component auto-pins it to the bottom of the panel (via the has-chat class on the scrollable wrapper) so it behaves like Streamlit's native chat layout.

import streamlit as st
from streamlit_floating_container import FloatingContainer

st.set_page_config(layout="wide")
st.title("My App")

if "chats" not in st.session_state:
    st.session_state["chats"] = []

def submit_chat(stkey):
    st.session_state["chats"].append(
        dict(who="user", message=st.session_state[stkey])
    )
    st.session_state["chats"].append(
        dict(who="ai", message="Response message")
    )

fp = FloatingContainer(
    icon=":material/chat:",
    label="Chat",
    start_position="middle",
    key="chat_float",
)

with fp.panel():
    # Message history
    for chat in st.session_state["chats"]:
        with st.chat_message(chat.get("who")):
            st.write(chat.get("message"))

    # Chat input placed directly in the container —
    # auto-pinned to the bottom of the panel.
    st.chat_input(
        "Type a message...",
        key="chat_input",
        on_submit=submit_chat,
        args=["chat_input"],
    )

Note: Only one st.chat_input widget is allowed per floating container. Additional chat inputs trigger a console warning and the panel will visually anchor the first one it finds.

FAQ / Static Content Example

import streamlit as st
from streamlit_floating_container import FloatingContainer

fp = FloatingContainer(
    icon=":material/help:",
    label="FAQ",
    start_position="bottom",
    key="faq",
    glassmorphic=False,  # solid background instead of frosted glass
)

with fp.panel():
    st.subheader("Frequently Asked Questions", anchor=False)
    st.markdown("**Q: How do I reset my password?**")
    st.markdown("A: Visit your profile page and click *Reset*.")
    st.divider()
    st.markdown("**Q: Who do I contact for support?**")
    st.markdown("A: Email support@example.com.")

API Reference

FloatingContainer

FloatingContainer(
    icon: str,
    label: str = "",
    start_position: Literal["top", "middle", "bottom"] = "top",
    key: str = "",
    glassmorphic: bool = True,
)

Parameters

Only one FloatingContainer instance may be mounted per page. Attempting to mount a second one raises RuntimeError.

panel() context manager

with fp.panel():
    st.write("This appears in the floating panel")

panel() enters the panel's scrollable container directly — anything you render inside the with block appears in the floating panel. You do not need a second nested with statement.

If you render a st.chat_input(...) inside the panel, the component automatically pins it to the bottom. No manual placement required.

Panel Controls

Styling

The component uses CSS variables from your Streamlit theme:

• --st-primary-color — button and accent colors
• --st-secondary-background-color — drag handle background, pinned chat-input background
• --st-text-color — text and icon colors

The panel features a glassmorphic design with blur effects and subtle shadows when glassmorphic=True. Set glassmorphic=False for a solid background that matches the theme.

Classes applied at runtime

Implementation Notes

• CCv2 component. Built on st.components.v2.component — the component is registered once at module import and mounted per render.
• No reload handshake. The component hot-updates from data on every render; no full-page reload or localStorage prop diff.
• DOM safety. Streamlit-managed nodes are never moved between trees; the component only toggles classes on them, avoiding React reconciler crashes (NotFoundError: insertBefore / removeChild) on reruns.
• Observers. A MutationObserver watches the scrollable area to keep the has-chat class in sync with the actual presence of a chat input, across reruns and conditional renders.
• Single-instance invariant. Mounting more than one FloatingContainer per page raises RuntimeError from Python.

File Structure

streamlit-floating-container/
├── pyproject.toml
├── README.md
└── streamlit_floating_container/
    ├── __init__.py
    ├── floating_container.html
    ├── floating_container.js
    └── styles.css

Development

git clone https://github.com/your-username/streamlit-floating-container.git
cd streamlit-floating-container
pip install -e .

Then run any demo script (e.g., main.py) with Streamlit:

streamlit run main.py

License

MIT