shiny-charts

Interactive charts for everyday Shiny for Python dashboards, available as an experimental beta for development and staging pilots. It has its own small semantic API and uses a bundled, modular Apache ECharts runtime. Plotly is not a runtime dependency.

The switching case is native theme integration, fewer repeated layout decisions, consistent interaction events, and a smaller browser bundle. The controlled FinOps comparison (recorded for 0.2.0a1) measured faster cold starts and reactive updates on this machine after profiling; the initial prototype had updates near parity. That comparison showed no websocket-size advantage for full reactive renders; proxy transport is measured separately, and performance depends on the workload. The beta supports common dashboard charts; Plotly's broader feature catalogue remains outside its scope.

Install the beta

The published beta is 0.4.0b5, with migration coverage and short-card fixes described below.

python -m pip install "shiny-charts==0.4.0b5"

Requires Python >=3.10, Shiny >=1.5, and htmltools >=0.6. The wheel includes the browser runtime; Node is not required to use it. Pandas and polars are optional.

Pin the exact beta version for reproducible pilots. This is an experimental release, not a general-availability stability promise. Validate required workflows, accessibility, and performance with representative data before production adoption. Supported chart families are line, area, bar, scatter, and histogram. R Shiny and Shinylive are outside this beta's supported scope. See the scope and API notes below.

Run the native FinOps app

uv sync --locked
uv run uvicorn examples.finops_app:app --host 127.0.0.1 --port 8056

Open native FinOps. It runs with Shiny and shiny-charts alone; Plotly is imported only by the separate comparison route. The four cards preserve workload/period filtering, request inspection, brush counts, histogram intervals, light/dark themes, persistent views, and exports. Dense scatterplots explicitly choose Canvas when the request-count setting is at least 10,000; smaller ones use SVG.

See the migration example and beta API contract. The current beta API contract applies to 0.4.0b5.

Run the second adoption app

uv run uvicorn examples.operations_app:app --host 127.0.0.1 --port 8057

Open service operations. This synthetic dashboard exercises long queue names, daily gaps, missing response/resolution pairs, a compact area card, queue filtering, selected record identity and a rolling observation window. Append 100 observations, revise measurements, or enable live batches every three seconds. It uses proxies for data updates and full renders for deliberate scope/dataset changes.

See incremental updates. Obtain a controller with proxy = renderer.proxy(); use await proxy.append(records, max_rows=...) or await proxy.replace_data(records). Appends send only new rows; the browser still redraws retained data. Full renders supersede old messages, and the update input reports application or rejection. Histograms use full renders to recompute bins.

Try the comparison

From this directory:

uv sync
uv run python -m uvicorn examples.app:app --host 127.0.0.1 --port 8055

Open shiny-charts and styled shiny-plotly. Both routes use the same synthetic FinOps data, Shiny controls, chart families, workload colors, request identifiers, success metadata, and filters. Plotly is deliberately styled to fit the dashboard. Try workload bar clicks, request inspection, rectangle selection, a theme change, zooming, hiding a series, and a simulated reactive update. The demo also supports 500, 2,400, 10,000, and 100,000 requests; the cold-start comparison uses 2,400 with SVG in both engines. At larger sizes the native scatter uses Canvas and Plotly still uses SVG, so those dashboard timings do not compare identical renderers.

Install the package in another environment with pip install /path/to/shiny-charts. The checked-in browser bundle makes Node unnecessary for Python users. To change the frontend, run npm ci && npm run build first.

Minimal Core app

from shiny import App, ui
from shiny_charts import chart, output_chart, render_chart

app_ui = ui.page_fluid(
    ui.input_dark_mode(),
    ui.card(
        ui.card_header("Monthly revenue"),
        output_chart("revenue", height="320px"),
        full_screen=True,
    ),
)

def server(input, output, session):
    @render_chart
    def revenue():
        return (
            chart.bar(
                {"month": ["Jan", "Feb", "Mar"], "revenue": [12, 18, 24]},
                x="month", y="revenue",
            )
            .format(y="currency:EUR")
            .labels(y="Revenue")
        )

app = App(app_ui, server)

Outputs without an explicit height fill their Shiny card; fixed-height outputs work outside fillable layouts. Core modules resolve output IDs through Shiny's namespace. In Express, use @render_chart directly inside with ui.card():; an output is created automatically. See examples/express_app.py, runnable with uv run shiny run examples/express_app.py.

Chart API

Builders accept a pandas or polars DataFrame, an iterable of record dictionaries, or a mapping of column names to equally sized lists. Pandas and polars are optional. Only the encoded fields, keys, requested tooltip fields, and band bounds are sent to the browser.

Builder	Encodings / options
chart.line(data, x=, y=)	color, key, tooltip, x_type
chart.area(data, x=, y=)	color, key, tooltip, stacked, x_type
chart.bar(data, x=, y=)	color, key, tooltip, stacked, orientation="horizontal"; categorical x
chart.scatter(data, x=, y=)	color, key, tooltip; numeric x/y
chart.histogram(data, x=)	bins=20, optional range=(min, max); server binning
chart.pie(data, names=, values=) (b5)	Nonnegative slice values; optional key, tooltip

Use color="workload" for grouped series. Category-to-color hashing keeps assignments stable when groups are filtered or reordered. Hash collisions are possible; use .palette({"Email": 1, "Chat": 2}) for distinct named roles in the host palette. Numeric and missing y values are accepted; missing observations produce line/band gaps. Date and datetime x columns infer a time axis; string dates need x_type="time". Datetimes normalize to UTC, naive datetimes are treated as UTC, and axis dates display in UTC. Explicit time strings should use ISO 8601 with an offset. Numeric x values infer a value axis for lines and areas.

The fluent operations return a new chart:

plot = (
    chart.line(daily, x="day", y="cost", color="workload")
    .format(y="currency:USD:3")
    .labels(x="Day", y="Cost / request", title="Daily request cost")
    .band(lower="low", upper="high", label="95% interval")
    .rule(y=0.045, label="Budget")
    .view("cost-v1")
)

Operation	Behavior
.format(x=, y=)	number[:digits], percent[:digits], currency:USD[:digits]; 0–6 digits
.palette({"Email": 1, "Chat": 2})	Named groups use one-based inherited palette slots 1–12; others retain the original six-colour hash
.labels(x=, y=, title=)	Axis labels, visible chart title (also exported), and accessible chart/table description
.band(lower=, upper=, label=)	Line/area interval using source columns, including intervals crossing zero
.rule(y=, label=)	Horizontal reference line
.domain(y=(0, 1), x=(None, 100))	Numeric min/max bounds; None retains an automatic bound; x requires a numeric value axis
.ticks(x_rotation=45, x_labels="auto")	Rotate semantic x ticks; b4 adds auto, all, or wrap category label modes
.value_labels(show=True, totals=False)	Formatted bar values (b4 hides zero/undersized stacked segments); optional positive/negative totals for stacked bars, recalculated for visible groups
.legend(order=["B", "A"])	Named groups first, then remaining groups in data order; also controls stack/series order
.data_table(hide=["internal_key"])	Hide encoded/tooltip columns in View data; CSV, tooltips, transport and selection keys are unchanged
.view(revision="default", zoom=True)	Preserve zoom/hidden series while revision stays the same; change it to reset client state and server selection/legend/view inputs. Zoom defaults to True; use zoom=False explicitly
.select(brush=False)	Enable point/category/bin clicks; rectangle brush is scatter-only
.renderer("svg")	SVG default; opt into "canvas" explicitly

Percent formats expect fractions (0.25 displays as 25%). Nonnegative stacked bar/area shares whose category totals are at most 1 use a 0–100% axis at every width, unless an explicit y domain, an out-of-range rule, or an out-of-range interval requires another scale. Values exceeding 100% are not clamped. Numeric tick spacing respects the displayed precision. b4 also divides fixed percent domains evenly, wraps few long category names at word boundaries, and preserves every category when rotation is requested. Dense date axes still thin rather than breaking date strings. Bar/histogram axes include zero; lines and scatterplots use data extents. Zoom uses Ctrl + mouse wheel so a dashboard remains scrollable. SVG export follows the SVG renderer; Canvas exports PNG. Charts with records include CSV export and a keyboard-accessible table preview of its first 250 displayed records. CSV includes all displayed records. Histogram CSV contains bins, not the unaggregated requests.

Shiny interaction

from shiny import reactive

# In server():
@reactive.effect
@reactive.event(input.requests_selection)
def selected():
    event = input.requests_selection()
    if event["kind"] == "records":
        selected_request.set(event["keys"][0])

For output_chart("requests"), available inputs are requests_click, requests_selection, requests_view, and requests_legend. Point clicks also emit a selection. Payloads carry the chart's view revision. A revision or renderer change emits selection clear, legend {hidden: []}, and view {reset: true} with the new revision, and clears the click input to None. Returning None or rendering an error clears all four interaction inputs to None. Same-revision data updates do not emit a selection automatically; applications still own reconciliation of selected keys after filtering at the same revision.

Selection kind	Payload
records	keys, x, y, group, original displayed row index
category	x, y, group, row, empty keys
bin	range: {min, max, upper_inclusive}, aggregated count
range	range: {x: [min,max], y: [min,max]}, count, keys, truncated
clear	Empty keys

Pass a non-null unique key column for record identity across filtering. Brush counts include only visible series and non-missing points. At most 10,000 record keys are sent; count remains exact and truncated reports the limit. Bins include their lower edge and exclude their upper edge, except the final bin includes the upper edge. View events report x-axis bounds or {reset: true}; legend events report hidden group names.

Theme integration

The chart reads computed styles from its actual output element. It inherits the font, Bootstrap body/secondary text, background, and border colors; transparent chart surfaces fit their containing card. Ancestor theme/class/style changes redraw in the browser. Dark mode and themes scoped to individual cards are supported.

Optional overrides live on any ancestor:

.my-dashboard {
  --chart-font: Georgia, serif;
  --chart-fg: #243044;
  --chart-muted: #596779;
  --chart-grid: #dce4ed;
  --chart-border: #dce4ed;
  --chart-surface: #ffffff;
  --chart-color-1: #087eac;
  /* --chart-color-2 through --chart-color-12 */
}

The library does not inject the demo's Manrope font or app palette. Those belong to the host dashboard. [data-bs-theme] selects theme mode; system preference supplies the fallback when there is no explicit theme.

Migrating from shiny-plotly

Replace output_plotly/render_plotly with output_chart/render_chart, then rebuild the figure using the semantic builders. Replace customdata IDs and nested Plotly click payloads with key= and the normalized event inputs. Put dashboard theme values in CSS, and use .view() where you previously used uirevision; pass zoom=False if the chart should not zoom.

There is no automatic conversion of go.Figure or Plotly Express figures and no Plotly compatibility layer. Start with one ordinary chart card and retain shiny-plotly for specialized charts. ECharts options are kept inside the frontend adapter; an arbitrary engine-options escape hatch is not part of this prototype's public API.

Verification and evidence

uv sync
npm ci
npm run build
npm test
uv run pytest -q
uv run ruff check src examples tests bench scripts
uv build
uv run python scripts/check_wheel.py
uv run python scripts/check_floor.py --python 3.10

Browser tests need Chromium (uv run playwright install chromium). Tests cover real Shiny Core/Express rendering, scoped themes, modules, click/brush identity, persistent views, table selection, CSV/image export, resizing, empty/error/None recovery, mobile overflow, and automated accessibility checks. Automated checks are not a claim of full screen-reader chart accessibility.

With the comparison server running, reproduce the local measurement:

uv run python bench/run.py --rounds 5
uv run python bench/write_report.py

The generated decision report records medians, environment, methodology, code-size comparison, and limits. Raw samples are in bench/results.json. These reports and review screenshots are local working material and excluded from commits.

Profile the large scatter path independently:

uv run python bench/profile_large.py
uv run python bench/write_profile_report.py

This profile separates Python builder/packing/JSON costs from actual SVG/Canvas completion for 10,000 and 100,000 points. It checks painted point counts and reports post-GC heap/DOM size. It is separate from the four-card cold-start benchmark. See the generated large-data report. Full updates still send complete chart specs; a smaller renderer bundle does not imply smaller event traffic or instant updates with large data.

Compare full versus proxy updates independently:

uv run python bench/updates.py

The generated incremental transport report measures received websocket bytes and completed Canvas updates for identical rolling keyed scatters. This compares two shiny-charts update paths, separately from Plotly timings.

Scope and next investment

Implemented: line, area, grouped/stacked bars, scatter, histogram, interval bands, horizontal rules, SVG/Canvas, linked filtering, theme inheritance, and exports. Beta b5 adds pie, x rules, data-coordinate annotations and formatted hover templates; see the migration APIs below. Missing: 3D, maps, facets, arbitrary mixed axes/layers, lasso, server resampling, point-level engine updates, automatic figure migration, and mature localization. R and Shinylive have not been validated. Normal reactive renders send complete specs; proxy appends send only new records while retaining the rendered definition. Long category labels and extreme numeric scales need broader layout testing.

The beta includes native FinOps and service-operations adoption apps, an explicit API/event contract, ordered data proxies, migration examples, dependency-floor and browser checks, and compatibility CI. The next external validation is a dashboard with actual user data and manual accessibility testing before production adoption. A custom Plotly partial bundle could narrow the cold-start advantage. See CONTRIBUTING.md for local checks.

MIT package; bundled ECharts/zrender retain their licenses and notices. See THIRD_PARTY.md.

Adopt in Portfolio pulse

make portfolio

Open Portfolio pulse. This local migration of an existing Python Shiny app retains its financial calculations, four filters and registered URL bookmarks. Its data is illustrative. The deployed original remains unchanged. The adoption development group installs shinyhub-bookmarks==0.5.2, which needs Shiny >=1.8; the chart library still supports Shiny >=1.5 and does not depend on that SDK. See the adoption notes.

Bar and area builders now accept tooltip=["field"], like line and scatter. Data tables use the encoded axis formats; CSV keeps raw values. Custom hosts can set --chart-hover and --chart-focus alongside the existing chart color tokens.

make profile-dashboard

This measures completed warm updates in Portfolio pulse and the four-card service operations app at desktop/mobile widths. It is a local workload measurement, not a Plotly comparison or a production throughput guarantee. Generated bench/report-dashboard.md and bench/results-dashboard.json stay local.

Synthetic client-pilot regressions

uv run uvicorn examples.pilot_app:app --host 127.0.0.1 --port 8059

This synthetic app exercises revision resets, server input state, percent shares, value/stack-total labels, optional table-column hiding, twelve explicit palette slots, dense dates, zero ticks, numeric domains, rotation, and None/empty/loading/error recovery. tests/test_pilot.py checks the same interactions in a real Shiny session. A zero-row chart clears axes and hides its toolbar. A renderer returning None shows a no-data message and disposes the previous chart. Missing-pair charts with records keep data/CSV access even when there is nothing to plot. Updating charts show a chart-level status message while keeping existing data visible.

The default hashed palette remains the original six colours for b1 compatibility. For eight distinct named groups, use .palette({name: i + 1 for i, name in enumerate(names)}). Slots 1–12 inherit --chart-color-1 through --chart-color-12 from the host; colour alone should not carry record identity. Table-column hiding is a presentation option, not data redaction: keys still reach the browser, selection events, and CSV exports.

Chart headings and empty messages (b3)

A visible .labels(title=...) heading appears above the legend and plot and is included in SVG/PNG exports. Apps whose card header already supplies the title can omit the chart title, or clear it with .labels(title=""), to avoid showing it twice. The full title stays in the accessible summary and View data heading; long visible headings truncate. Image export preserves the current rendered view.

For a chart that is not filter-driven, customize its no-data message in Core:

output_chart("observations", empty_message="No observations available yet.")

Or configure the automatic output in Express:

@render_chart(empty_message="No observations available yet.")
def observations():
    return None

The message must be a non-empty string and is rendered as literal text. It applies to None, zero-row data, and records without plottable values. Core uses the message on its explicit output_chart; the renderer option configures automatic output UI. The existing default message remains unchanged.

Adoption and server capacity

See server footprint and construction measurements for a reproducible fresh-process RSS benchmark, warm spec CPU timings, chart coverage, and the remaining migration gaps. These measurements exclude dashboard aggregation and do not predict session capacity on another host.

Full-migration APIs (b5)

chart.pie(rows, names="status", values="n", key="id", tooltip=["share"]).hover(
    template="{status}: {n:number:0} ({share:percent:1})"
)

chart.line(daily, x="day", y="n", tooltip=["share"]).rule(
    x=date(2026, 1, 2), label="Cutoff"
).annotate(x=date(2026, 1, 2), y=12, text="Peak", position="bottom").hover(
    formats={"share": "percent:1"}
)

Import date from datetime for the date example. Pie values are nonnegative; missing values are omitted from slices, and an all-zero pie shows the empty message while retaining its data table and CSV. Slice events retain original row keys. Repeated names form separate slices controlled by one legend group; aggregate first if one slice per category is intended. Pie accepts palette/legend/hover/selection controls; axis domains, ticks, reference rules and plot annotations require Cartesian charts. Donuts are not included.

.rule accepts exactly one of semantic x or y; x rules follow dates/categories and map correctly on horizontal bars. .annotate uses data coordinates and plain text, with top, bottom, left, right or inside placement. Unknown category coordinates are omitted until the category appears; explicit domains clip plot text. Annotations are silent, export with the chart, and may extend automatic axis bounds. Position them to avoid obscuring important marks; annotation collision resolution is not automatic.

Hover template fields are actual column names already encoded or explicitly requested via tooltip=[...]. {field} uses its default display; {field:percent:1}, number and currency formats override it. Double braces produce literal braces; newlines produce line breaks. HTML and data are escaped, and expressions, attribute access, conversions and nested formats are not evaluated. Per-column .hover(formats=...) affects hover only, leaving table/CSV values and axis formatting unchanged.

.legend(layout="scroll", placement="bottom") creates a keyboard-accessible single scrolling row below the plot. The defaults remain wrapping and top placement. Order, placement and layout can be configured in separate calls. Narrow-card toolbars show icons with complete accessible action names and native title tooltips, retaining a single row; very short widths can scroll horizontally.

Rotated tick width is bounded by the actual output height, preserving plotting space and keeping the axis title close to the labels. Long ticks truncate in short outputs; use a taller output for complete rotated labels. Wide numeric ticks reserve room for the y-axis name, with truncation only where the card cannot accommodate the values.

Run the synthetic coverage app with uv run uvicorn examples.adoption_app:app --port 8059. The benchmark guide now separates macOS measurements from reported Linux results: small aggregated bars can benefit, while many-series bars and large scatter charts have no general CPU or payload advantage.