Summary
When no built-in widget fits, write your own R, Python or SQL code directly in a widget. The code receives your filtered dataset in a dataset variable, and its output can be a chart, a table, a value or HTML.
Why a code widget
The catalogue plugins cover common analyses, but sometimes you need a specific computation: a custom transformation, a chart with a particular library, a composite indicator. By choosing the Custom code tab in the Add a widget dialog, you write exactly what you want, without leaving the dashboard.
Age
Choosing the language
In the Custom code tab, choose Python, R or SQL. The best language depends on your habits and the task:
- Python builds on the pandas / matplotlib ecosystem for data wrangling and visualisation.
- R suits statistical analyses and
ggplot2/ base R graphics. - SQL is for querying and aggregating the dataset declaratively.
Client mode: everything in the browser
In client mode (no backend), the code runs in your browser thanks to WebAssembly ports: Pyodide for Python, WebR for R, and DuckDB-WASM for SQL. Your data then never leaves the machine. The first run loads the environment (a few seconds); later runs are faster. With a backend, execution can happen server-side — see the deployment modes.
Accessing the data
Your code automatically receives the widget’s dataset, already filtered by the dashboard’s active filters:
- In Python, the variable
datasetis a pandas DataFrame. Columns keep their readable names (e.g.dataset["age"]). - In R, the variable
datasetis a data.frame with the same columns.
So you just read dataset and produce your output.
import matplotlib.pyplot as plt
ax = dataset["age"].hist(bins=20)
ax.set_xlabel("Age")
ax.set_ylabel("Count")
plt.show()library(ggplot2)
ggplot(dataset, aes(x = age)) +
geom_histogram(bins = 20) +
labs(x = "Age", y = "Count")Filters apply before your code
The dataset your code receives already reflects the dashboard’s filters. When the user changes a filter, the code widget re-runs on the new rows — your code does not need to do anything special.
Output types
The widget renders whatever your code produces:
Chart
A matplotlib / ggplot / base R figure, rendered as a crisp image (vector when possible).
Table
A DataFrame or data.frame shown as a table.
Value
A printed number or text — useful for a simple indicator.
HTML
Raw HTML, for a custom rendering directly in the widget.
If something goes wrong, the standard output and error messages (stdout / stderr) appear in the widget to help you fix it.
One-off code or reusable plugin?
A code widget is ideal for a one-off analysis specific to a dashboard. If you find yourself copying the same code from project to project, package it as a plugin instead: it becomes configurable, shareable and shows up in the widget list. See Build a plugin.