Airflow Widgets – Python-Driven UI Extensions

Airflow Widgets is an experimental framework that lets data engineers extend the Airflow UI using pure Python. Instead of writing React per use-case, teams declare widgets (Markdown, tables, Mermaid diagrams) that are rendered dynamically inside the Airflow web UI.

Situation

Airflow exposes rich operational metadata, but the UI is largely static. Teams often rely on external docs, dashboards, or tribal knowledge during incidents.

Task

Surface runbooks, lineage, and operational metrics directly inside Airflow—without forcing Python engineers to learn React.

Action

Built an Airflow plugin that bridges Python → FastAPI → React. Python returns declarative widget specs; React renders them generically.

Result

DAGs and task instances become self-documenting. Support engineers get context where failures happen: in the task instance view.

Tech stack & source
🌀Apache Airflow
🐍Python
⚡FastAPI
⚛️React
View on GitHub

High-level architecture

Airflow Widgets splits responsibilities across three layers: orchestration, widget definitions, and rendering.

Apache Airflow
Airflow loads DAGs and task instances. The React panel receives context props (dagId, taskId, runId) when the task instance UI is opened.
FastAPI Widget API
FastAPI loads Python widget functions and returns a list of widget specs (Markdown / table / Mermaid) as JSON.
Embedded React UI
React is a generic renderer: it fetches widget JSON and renders the right widget component based on type.

How it works

At runtime, the panel reads Airflow props, calls the FastAPI route, receives widget JSON, and renders it.

Step 1 – Apache Airflow

Airflow loads DAGs and task instances and passes rich context to the plugin runtime.

1
Airflow renders the task instance page and mounts the React plugin panel.
2
The panel calls /widgets-plugin/api/task/<dag>/<task> to fetch widget specs defined in Python.
3
The renderer maps type → component (Markdown/Table/Mermaid) and displays them inside Airflow.

Currently supported widgets

  • 📄 Markdown (runbooks, descriptions, summaries)
  • 📊 Tables (metrics, costs, metadata)
  • 🧬 Mermaid diagrams (lineage, architecture)

⚠ Experimental project

Airflow Widgets is an experiment. The goal is to prove a possibility: the Airflow UI can be meaningfully extended using Python-first widget declarations, instead of requiring every feature to be written in React. It’s not production-hardened yet, but it’s a solid foundation for UI extensions owned by backend/data platform teams.

Example widget outputs (real UI)

These examples mirror what operators see inside the Airflow task instance view. The content is declared in Python; the UI is rendered dynamically.

DBT – dim_products
Operators see model context directly on the task instance page—no switching to dbt docs during incidents.
  • Support runbook (Markdown): triage steps, owner, SLA
  • Model description: business context for analysts
  • Metadata & lineage: materialization + relation + upstream nodes
  • Mermaid lineage diagram: upstream → model
  • Last run summary: status, execution time, adapter response
  • Columns table: column docs + types (optional catalog stats)
DBT task widgets inside Airflow task instance UI
DBT task widgets inside Airflow task instance UI
Example: SUCCESS · 12,483 rows · 4.2s
Tip: put screenshots in /public/projects/airflow-widgets/ and update the src paths above.

If you like this idea, please ⭐ the repository and check out more projects on rahulrajasekharan.dev.