streamlit-shadcn-ui

shadcn components for Streamlit, implemented on Streamlit Components V2.

The 1.x package uses checked-in shadcn source backed by Base UI, React 19, Tailwind CSS 4, and Streamlit's isolated Shadow DOM runtime. Components render without an iframe. Anchored and modal overlays stay in their own component ShadowRoot and use the browser top layer, so Select, Combobox, Dropdown Menu, Popover, Hover Card, Date Picker, Alert Dialog, and Elements Dialog, Sheet, or Tooltip are not clipped by the Streamlit layout.

Installation

pip install streamlit-shadcn-ui

Python 3.10 or newer and Streamlit 1.60 or newer are required.

The verified host combination for the 1.5.0 component changes is Streamlit 1.60.0 with Starlette 1.3.1. When using Streamlit 1.60, pin that tested Starlette version:

pip install "streamlit==1.60.0" "starlette==1.3.1" streamlit-shadcn-ui

Fresh resolution with Starlette 1.10.0 caused intermittent component-asset serving errors during acceptance. Other host combinations need separate verification; see the release notes.

Quick start

import streamlit as st
import streamlit_shadcn_ui as ui

fruit = ui.select(
    "Fruit",
    ["Apple", "Banana", "Orange"],
    value="Banana",
)

enabled = ui.switch("Enable notifications", value=True)

if ui.button("Save", variant="default"):
    st.write({"fruit": fruit, "enabled": enabled})

key is optional for ordinary calls. Add a stable key when components are created from a loop, can be reordered, or need identity that survives changes to their other arguments:

for project in projects:
    ui.checkbox(project.name, key=f"project_{project.id}")

Choice components return the original Python values rather than their display labels. Use format_func, Choice, or MenuItem to customize presentation without changing the returned value.

Components

• Choice and action: select, combobox, dropdown_menu, radio_group, button, link_button, breadcrumb, pagination
• Inputs: checkbox, input, input_group, number_input, textarea, input_otp, slider, switch, toggle, toggle_group
• Date and navigation: calendar, date_picker, tabs, accordion, collapsible
• Overlays: popover, hover_card, alert_dialog; Elements also provides Dialog, Sheet, and Tooltip composition
• Display: alert, avatar, badge, badges, card, metric_card, aspect_ratio, progress, scroll_area, separator, skeleton, table
• Records: data_table adds local sorting, search, pagination, column visibility, stable row selection, and one-shot row actions
• Composition: elements creates one nested, stateful React tree from typed Card, Button Group, Dialog, Sheet, Empty, Field, Item, Avatar, Tooltip, Spinner, Tabs, Accordion, Collapsible, Scroll Area, layout, content, input, choice, and action nodes
• Charts: line_chart, area_chart, bar_chart, pie_chart, radar_chart, radial_chart accept records or DataFrames with native shadcn tooltips and legends. See Charts for options and data limits.

with ui.elements(key="settings") as el:
    with el.card(key="account"):
        with el.card_header():
            el.heading("Account")
            el.text("Manage your preferences.", variant="muted")
        with el.card_content():
            email = el.input("Email", key="email")
        with el.card_footer():
            save = el.button("Save", key="save", stretch=True)

st.write(email.value, save.clicked)

See the Elements documentation, the V2 technical assessment, and the independent shadcn homepage-card use case. Version 1.5.0 adds four component groups: nested Elements containers, Item, Sheet, and Data Table. The records example combines a Data Table with a Sheet editor and saves edits back to the table. Data Table supports up to 1,000 local rows and remains a standalone widget. See the composition matrix for widget and Elements support. Release changes are recorded in the changelog and the 1.5.0 release notes.

The documentation app uses Home.py as its explicit router. Its product homepage, interactive Playground, and component pages are executable documentation for the complete catalog.

Architecture

The production component path is deliberately kept recognizable and upgradable:

Python API
  -> Streamlit Components V2 adapter
    -> owned generated shadcn component
      -> Base UI behavior primitive

shadcn owns the component palette, radius, typography, focus rings, and interaction styling. Streamlit provides the surrounding light/dark color scheme, language, and direction. The package does not restyle shadcn to look like Streamlit.

Ordinary helper calls are independently isolated V2 components. Precomposed helpers such as Card, Popover, and Collapsible accept documented text or data arguments. ui.elements is the opt-in aggregate path: its complete typed tree is rendered in one V2 root. Neither path accepts native Streamlit elements as React children.

See the 1.0 API decision, architecture plan, and V1-to-1.0 migration guide for the detailed contracts.

Migrating from 0.1.x

The 1.0 package root is the V2 API. The V1 iframe implementation and streamlit_shadcn_ui.v1 compatibility namespace are not shipped. Applications that cannot migrate yet should remain on the last 0.1.x release.

The most common source changes are:

• button(text=...) becomes button(label=...);
• grouped V1 checkboxes become ordinary composition of scalar checkboxes;
• with ui.card(...) becomes Streamlit layout around a declarative Card;
• low-level trigger/content helpers and experimental element() trees are removed;
• component return values and callbacks replace reliance on raw session-state transport dictionaries.

The full mapping is in the compatibility matrix.

Development

Follow the repository's AGENTS.md. Changes to shadcn default styles, including overrides in adapters or documentation CSS, require explicit user permission.

Use Node 22.20.0 and the pnpm version pinned in the frontend manifest.

./scripts/frontend_v2.sh            # watch the V2 frontend build
./scripts/dev.sh                    # run the documentation app
./scripts/verify_v2_release_source.sh
python3 -m unittest discover -s tests/v2

The Python implementation lives in streamlit_shadcn_ui/v2, generated and adapted frontend source in streamlit_shadcn_ui/frontend_v2, and release assets in streamlit_shadcn_ui/frontend_v2/dist.

References

• Streamlit
• shadcn/ui
• Base UI

License

MIT. See LICENSE.