streamlit-pydantic-object-builder

Streamlit custom component for building and editing Pydantic v2 objects with a drag-and-drop UI.

The widget returns a validated Pydantic model instance (or None while the draft is invalid). JSON is only used as the component wire format.

Install

pip install streamlit-pydantic-object-builder

Requires Python ≥ 3.10, Streamlit ≥ 1.62, and Pydantic ≥ 2.

Quick start

import streamlit as st
from pydantic import BaseModel
from streamlit_pydantic_object_builder import pydantic_object_builder

class Hair(BaseModel):
    color: str
    length: str

class Person(BaseModel):
    name: str
    age: int
    hair: Hair | None = None

result = pydantic_object_builder(
    edit_object=Person(name="Rhubarb", age=41, hair=Hair(color="red", length="short")),
    library=[Hair(color="brown", length="long")],
    label_fields={Hair: "color"},
    return_on_change=True,
    key="person_editor",
)

if result is None:
    st.warning("Draft does not currently validate")
else:
    st.json(result.model_dump(mode="json"))

Pass a model class instead of an instance to start from defaults / empty placeholders.

API

pydantic_object_builder(
    edit_object,
    library=None,
    *,
    return_on_change=True,
    save_button_position="bottom-left",
    label_fields=None,
    key=None,
    disabled=False,
    hide_library=False,
    min_height=360,
    on_change=None,
    on_save=None,
    seed=None,
) -> BaseModel | None

edit_object is the initial value for a given key (like other Streamlit widgets). To load a different object into the same editor, pass a new seed or key.

Features

• Nested models with compact summaries, click-to-expand, pencil to open a nested view, Expand all / Collapse all, Undo / Reset
• Library pane: search, accordion by type, blank “New {Type}” cards, copy-on-drop
• Lists and sets: reorder, insert (+), duplicate, trash-to-remove, drop-to-replace
• Enums, Literal, date / time / datetime, dict, tuples, unions (including discriminators)
• UUID, Decimal, EmailStr / HttpUrl (when the matching Pydantic extras are installed)
• Field metadata: description, examples, numeric and string constraints
• Inline validation errors; unsupported types shown read-only
• Streamlit theme tokens and SVG icons

Development

Clone the repo, then:

python -m pip install -e ".[devel]"
cd streamlit_pydantic_object_builder/frontend
npm install
npm run build

If your environment uses TLS interception, npm install --strict-ssl=false may be required.

streamlit run example.py
pytest -q
cd streamlit_pydantic_object_builder/frontend && npm test

During frontend development, run npm run dev in frontend/ and streamlit run example.py in the repo root.

Optional Playwright smoke (demo must be running):

cd streamlit_pydantic_object_builder/frontend
npx playwright install chromium
E2E=1 npx playwright test

Frontend assets are built into the wheel; they are not committed.

cd streamlit_pydantic_object_builder/frontend
npm ci
npm run build
cd ../../
python -m build