marimo-utils 0.8.0

Utilities for working with marimo notebooks: Pydantic model display plus a Tailwind + shadcn UI primitives package

marimo-utils

Utilities for working with marimo notebooks.

Installation

pip install marimo-utils

Usage

marimo_utils.pydantic — Pydantic model display in marimo

Adds marimo's _display_ protocol to Pydantic models so the last expression in a cell renders class name, source path, and field values.

from pydantic import BaseModel
from marimo_utils import add_marimo_display

@add_marimo_display()
class MyConfig(BaseModel):
    name: str
    value: int

When a MyConfig instance is the last expression in a marimo cell, it renders with the class name, source file path, and all field values.

Package layout (marimo_utils)

Path	Role
pydantic/	Pydantic ↔ marimo integration — add_marimo_display(), render_model()
ui/	Styled widget + chart toolkit (see below)

Import from marimo_utils or marimo_utils.pydantic in notebooks; internal paths may change between releases.

marimo_utils.ui — Tailwind + shadcn primitives for marimo

Pydantic-backed UI primitives that render through Tailwind (Play CDN) themed with shadcn/ui defaults. The package ships card components (Card, CardTitle, CardDescription), small composable atoms (Badge, DataItem, Stamp, date_stamp, project_stamp, LabeledList, LucideIcon), and a plotly-backed chart family (BarChart, HeatmapChart, HistogramChart, LineChart, PieChart, ScatterChart, ViolinChart) sharing a common PlotlyChart base. Call bootstrap_tailwind() once in a notebook to inject shadcn's CSS variables on :root plus the utility rules that depend on them, then load the Tailwind CDN.

import marimo as mo
from marimo_utils.ui import (
    BarChart,
    BarItem,
    Card,
    CardWidth,
    ChartColor,
    bootstrap_tailwind,
)

bootstrap_tailwind()

Card(
    title="Class Distribution",
    description="Class counts across the training split",
    content=BarChart(
        items=[
            BarItem(label="Class A", value=5),
            BarItem(label="Class B", value=10),
            BarItem(label="Class C", value=5, color=ChartColor.THREE),
            BarItem(label="Class D", value=1),
        ],
        height=220,
    ),
    width=CardWidth.NARROW,
).render()

Components use shadcn's stock variant names (default, secondary, destructive, outline). Meta rows use registry-backed stamp builders — date_stamp() and project_stamp() return a Stamp with configurable empty text, spacing, and icons. Charts cycle through the --chart-1 → --chart-5 palette by default; pin specific items with color=ChartColor.X. Every PlotlyChart subclass renders through the same contract: plotly HTML with responsive: true + include_plotlyjs="cdn", a .reactive() opt-in for marimo-reactive widgets, and a Card-friendly transparent background. <script>-bearing HTML (plotly) is routed through dr_widget.inline.ActiveHtml so charts execute inside marimo's React tree.

See nbs/ui_components.py for a live demo of every atom, chart, and card variant side-by-side.

Styling conventions (styles.py)

Tailwind class strings are centralized in marimo_utils.ui.styles as named enums and constants. Components compose them with cn() from drhtml (tailwind-merge); pass per-instance overrides through each component's klass prop last.

Group	Symbols	Role
Layout	DivLayouts, SpanLayouts	Card sections, inline rows, key/value rows, icon frame
Typography	Typography	Text size, weight, and color
Sizing	IconSize, CardWidth, Padding	Icon dimensions, card widths, badge padding
Surface	BORDER, BADGE_FOCUS, Background	Shared border/radius/shadow, focus ring, fills and hovers
Badges	BadgeVariant	Shadcn badge variants (aliases into Background)

Contributors and agents: avoid raw layout Tailwind in components; add or reuse a named enum or shared constant instead.

Package layout (marimo_utils.ui)

Path	Role
setup/	Notebook bootstrap — bootstrap_tailwind() and shadcn CSS injection
core/	HTML DSL — drhtml tag builders, cn(), rendering helpers
styles.py	Shared Tailwind token enums and constants
components/	UI widgets (Card, Badge, Stamp, …)
charts/	Plotly chart family and colors palette helpers

Import from marimo_utils.ui in notebooks; internal paths may change between releases.

Changelog

See CHANGELOG.md for release notes and migration guides.