Metadata-Version: 2.4
Name: streamlit-shadcn-ui
Version: 1.5.0
Summary: Using shadcn components in Streamlit
Author-email: Observed Observer <ooer@kanaries.net>
License-Expression: MIT
Project-URL: homepage, https://github.com/ObservedObserver/streamlit-shadcn-ui
Project-URL: repository, https://github.com/ObservedObserver/streamlit-shadcn-ui
Keywords: streamlit,shadcn,ui,components
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: streamlit>=1.60
Dynamic: license-file

# streamlit-shadcn-ui

[![PyPI - Version](https://img.shields.io/pypi/v/streamlit-shadcn-ui)](https://pypi.org/project/streamlit-shadcn-ui/)
![PyPI - Downloads](https://img.shields.io/pypi/dm/streamlit-shadcn-ui)
[![Streamlit App](https://static.streamlit.io/badges/streamlit_badge_black_white.svg)](https://shadcn.streamlit.app/)

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

```sh
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:

```sh
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](docs/releases/1.5.0.md).

## Quick start

```python
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:

```python
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](docs/components/charts.md) for options and data limits.

```python
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](docs/components/elements.md), the
[V2 technical assessment](docs/elements-v2-technical-assessment.md), and the
[independent shadcn homepage-card use case](pages/Elements.py).
Version 1.5.0 adds four component groups: nested
[Elements containers](docs/components/elements.md#nested-panels-and-scroll-regions),
[Item](docs/components/item.md), [Sheet](docs/components/sheet.md), and
[Data Table](docs/components/data_table.md). 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](docs/elements-support-matrix.md) for widget and Elements
support.
Release changes are recorded in the [changelog](CHANGELOG.md) and the
[1.5.0 release notes](docs/releases/1.5.0.md).

The documentation app uses [Home.py](Home.py) as its explicit router. Its
[product homepage](site_pages/Homepage.py), interactive
[Playground](site_pages/Playground.py), and [component pages](pages) are
executable documentation for the complete catalog.

## Architecture

The production component path is deliberately kept recognizable and
upgradable:

```text
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](docs/adr/011-v2-1.0-python-api.md),
[architecture plan](docs/v2-production-migration-plan.md), and
[V1-to-1.0 migration guide](docs/v2-compatibility-matrix.md) 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](docs/v2-compatibility-matrix.md).

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

```sh
./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](https://streamlit.io/)
- [shadcn/ui](https://ui.shadcn.com/)
- [Base UI](https://base-ui.com/)

## License

MIT. See [LICENSE](LICENSE).
