> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gp.scale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Widget Types Overview

> Overview of all available widget types for evaluation dashboards

Dashboard widgets are visualization components that display evaluation data in different formats. This guide provides an overview of all available widget types.

## Available Widget Types

### Data-Driven Widgets

These widgets require queries and compute results from evaluation data:

<CardGroup cols={2}>
  <Card title="Metric Widget" icon="hashtag" href="./metric">
    Display a single computed value like averages, counts, or percentiles
  </Card>

  <Card title="Table Widget" icon="table" href="./table">
    Show multi-dimensional data in rows and columns with grouping, sorting, and conditional formatting
  </Card>

  <Card title="Bar Chart" icon="chart-bar" href="./bar">
    Visualize comparisons across categories with bar charts
  </Card>

  <Card title="Histogram" icon="chart-simple" href="./histogram">
    Display data distributions across numerical ranges
  </Card>

  <Card title="Donut Chart" icon="chart-pie" href="./donut">
    Show proportional distribution of categories as a donut/pie chart
  </Card>

  <Card title="Scatter Plot" icon="chart-scatter" href="./scatter">
    Explore correlations between two numerical dimensions
  </Card>

  <Card title="Timeseries" icon="chart-line" href="./timeseries">
    Track metrics over time with line charts
  </Card>
</CardGroup>

### Static Content Widgets

These widgets display static content without queries:

<CardGroup cols={2}>
  <Card title="Markdown Widget" icon="file-lines" href="./markdown">
    Add rich text documentation, instructions, and notes
  </Card>

  <Card title="Heading Widget" icon="heading" href="./heading">
    Organize dashboards with section headers
  </Card>
</CardGroup>

## Quick Reference

| Widget Type    | Purpose                        | Requires Query | Best For                                |
| -------------- | ------------------------------ | -------------- | --------------------------------------- |
| **Metric**     | Single aggregation value       | Yes            | Top-level metrics, summary stats        |
| **Table**      | Tabular data display           | Yes            | Detailed breakdowns, grouped data       |
| **Bar**        | Bar chart visualization        | Yes            | Categorical comparisons                 |
| **Histogram**  | Distribution visualization     | Yes            | Understanding distribution of data      |
| **Donut**      | Proportional distribution      | Yes            | Category breakdowns, percentage views   |
| **Scatter**    | X-Y relationship visualization | Yes            | Correlations, outlier detection         |
| **Timeseries** | Trends over time               | Yes            | Tracking metrics across evaluation runs |
| **Markdown**   | Rich text content              | No             | Documentation, instructions, notes      |
| **Heading**    | Section headers                | No             | Dashboard organization                  |

## Choosing the Right Widget Type

### Display a Single Number

Use a **Metric widget** when you need to show one computed value prominently:

* Overall average score
* Total item count
* Pass rate percentage
* 95th percentile latency

### Show Detailed Breakdowns

Use a **Table widget** when you need to display multiple dimensions and metrics:

* Performance by model and category
* Top 10 highest/lowest scoring items
* Multi-column statistical summaries

### Compare Categories

Use a **Bar Chart widget** to visualize how values differ across groups:

* Score by category
* Model performance comparison
* Items per status

### Visualize Distributions

Use a **Histogram widget** to understand how values are distributed:

* Score distribution
* Latency distribution
* Confidence level spread

### Show Proportional Breakdowns

Use a **Donut Chart widget** to visualize how categories are distributed:

* Task type distribution
* Agent workload share
* Prompt category breakdown

### Explore Correlations

Use a **Scatter Plot widget** to examine relationships between two metrics:

* Accuracy vs. relevance
* Score vs. response length
* Latency vs. quality

### Track Trends Over Time

Use a **Timeseries widget** to monitor metrics across evaluation runs:

* Score progression across evaluations
* Multi-metric trends in evaluation groups
* Performance tracking over time

### Add Documentation

Use **Markdown widgets** for context and instructions:

* Dashboard methodology
* Alert thresholds
* Team contact information
* Analysis guidelines

### Organize Sections

Use **Heading widgets** to structure your dashboard:

* "Overview Metrics"
* "Detailed Analysis"
* "Performance by Category"

## Widget Configuration Overview

All widgets share common fields:

**Required Fields:**

* `title`: Display name for the widget
* `type`: One of: metric, table, bar, histogram, donut, scatter, timeseries, markdown, heading

**Query Field (for data-driven widgets):**

* `query`: QueryAST object defining the computation

**Optional Fields:**

* `config`: Widget-specific display configuration

## Data Sources

Data-driven widgets can query two sources:

* **`data.*`**: User-defined evaluation data (your custom fields)
* **`task_result_cache.*`**: Task execution results

Both support nested fields using dot notation (e.g., `data.metadata.model_version`).

## Reusing Widgets

Widgets can be shared across multiple dashboards. When you include the same widget ID in different dashboards' `widget_order`, they all use the same widget definition but produce different results based on their evaluation context.

<Warning>
  When reusing widgets, make sure the shape of the data for each evaluation is the same. Otherwise, the widget will not be able to compute the result.
</Warning>

## Next Steps

Explore detailed documentation for each widget type:

* [Metric Widget](./metric) - Single value displays
* [Table Widget](./table) - Tabular data with conditional formatting
* [Bar Chart Widget](./bar) - Category comparisons
* [Histogram Widget](./histogram) - Distribution visualization
* [Donut Chart Widget](./donut) - Proportional distributions
* [Scatter Plot Widget](./scatter) - Correlation analysis
* [Timeseries Widget](./timeseries) - Trends over time
* [Markdown Widget](./markdown) - Rich text content
* [Heading Widget](./heading) - Section headers

Or continue learning:

* [Evaluation Group Dashboards](../eval-group-dashboards) - Compare across evaluations
* [Query Language](../query-language) - Build powerful queries
* [Getting Started](../getting-started) - Create your first dashboard
* [API Reference](/reference/v5/evaluation-dashboards) - Explore programmatic query creation