Vizro Documentation

Understanding how custom actions function in Vizro is essential for building interactive dashboards.

• Definition: An action is a Python function triggered by user interaction with a component.
• Inputs/Outputs: An action can have any number of inputs and outputs, but it is associated with exactly one trigger.
• Chaining: Actions can be linked in two ways:
  • Explicitly: Using the actions=[action_1, action_2, ...] parameter. In this mode, action_2 only begins after action_1 has successfully completed.
  • Implicitly: When an action's output automatically satisfies the input requirements of another action, triggering it.
• Execution: When multiple actions are triggered at the same time, they typically execute in parallel.
• Error Handling: You can stop the execution of an action and prevent any subsequent chained actions from running by raising an exception.
• Security: Always treat action inputs as untrusted data, as they are generated by the user.

Vizro occupies a niche between low-level Python visualization libraries (like Plotly/Dash or Streamlit) and proprietary Business Intelligence (BI) tools (like Tableau or PowerBI).

Key differentiators include:

• Assembly System: Uses a configuration-driven approach to build high-level dashboard concepts (e.g., filters) from low-level components, reducing the need for manual "glue code."
• Inbuilt Design & Architecture: Provides automatic UX/visual design decisions (spacing, colors, placement) and application architecture (navigation, drill-throughs) to ensure consistency.
• Declarative Configuration: Supports multiple formats including Python, YAML, JSON, and TOML, allowing for programmatic dashboard generation (e.g., via Kedro pipelines).
• Grammar of Dashboards: Uses a mostly tech-agnostic configuration language rather than being strictly tied to a specific Python package syntax.
• Inbuilt Validation: Leverages Pydantic models to provide early, meaningful feedback on configuration choices.
• Modularity & Scaling: Enables reuse of entire dashboard screens and configurations across projects. It is designed for Git-based collaboration and programmatic updates from a central location.
• Flexibility: Combines a low-code configuration approach for simple tasks with a high-code approach (custom Python functions) for infinite extensibility.

Vizro uses a JSON schema to define a "grammar of dashboards," providing a unified, implementation-independent language to configure dashboards. This schema allows you to define dashboards using Python, JSON, or YAML.

A valid dashboard configuration generally requires:

• A title (string)
• pages (an array of Page objects)
• A theme (either vizro_dark or vizro_light)

Each Page must contain:

• A title (string)
• components (an array of component objects, e.g., Graph, Table, AgGrid, Card, Button, Container)
• Optional controls (an array of Filter or Parameter objects)

Note: The schema is evolving. Some features, like CapturedCallable objects used in figure arguments, may not be explicitly defined in the schema yet but can still be configured via JSON.

{
  "pages": [
    {
      "components": [
        {
          "figure": {
            "_target": "scatter",
            "color": "species",
            "data_frame": "iris",
            "x": "sepal_length",
            "y": "petal_width"
          },
          "type": "graph"
        }
      ],
      "controls": [
        {
          "column": "species",
          "type": "filter"
        }
      ],
      "title": "My first dashboard"
    }
  ]
}