Summary
When no built-in widget fits, write your own R or Python 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 or R. 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.
Why no SQL?
Code widgets offer Python and R, but not SQL. A widget works on a dataset — a file, not a database connection — so a SQL query would have nothing to query. For SQL, address the database itself from the SQL script collections.
Where the code runs
In client mode (no backend), the code runs in your browser thanks to WebAssembly ports: Pyodide for Python and WebR for R. Your data never leaves the machine. The first run loads the environment (a few seconds); later runs are faster.
In server mode, the code runs on the server: it reads the dataset and applies the dashboard filters itself, so no data rows are sent to the browser. Each widget runs in its own process, so the widgets of a tab execute in parallel. 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.