Dashboard Panels

Complete guide to panel types, configuration, and organization in Grafana dashboards.

Dashboard Panels

Panels are the building blocks of Grafana dashboards. Each panel displays a visualization of your data using queries, transformations, and customizable options.

Panel Model

The PanelModel class represents a panel’s configuration and state:

interface PanelModel {
  id: number;                    // Unique panel ID within dashboard
  type: string;                  // Visualization type (e.g., "timeseries")
  title: string;                 // Panel title
  gridPos: GridPos;              // Position and size on grid
  targets: DataQuery[];          // Array of queries
  transformations?: DataTransformerConfig[];  // Data transformations
  datasource: DataSourceRef | null;  // Data source reference
  options: Record<string, any>;  // Panel-specific options
  fieldConfig: FieldConfigSource;  // Field configuration and overrides
  transparent: boolean;          // Transparent background
  description?: string;          // Panel description
  links?: DataLink[];            // Panel links
}

Panel Types

Grafana includes many built-in visualizations:

Time Series Visualizations

Time Series

Line, bar, and area charts for time-series data with multiple series support

State Timeline

Visualize state changes over time with categorical data

Status History

Show periodic state over time in a grid format

Trend

Display trends and sparklines for single metrics

Statistical Visualizations

Stat

Single value with optional graph and thresholds

Gauge

Radial or linear gauge for displaying single values

Bar Gauge

Horizontal or vertical bars with threshold colors

Heatmap

Visualize value distribution over time in a heat map

Graph Visualizations

Bar Chart

Categorical data visualization with grouped or stacked bars

Histogram

Distribution of values across buckets

Pie Chart

Proportional data visualization

Candlestick

Financial data with OHLC (Open, High, Low, Close) values

Data Visualizations

Table

Tabular data display with sorting, filtering, and formatting

Logs

Log line display with parsing and filtering

Node Graph

Network topology and relationship visualization

Traces

Distributed tracing visualization

Geo & Special

Geomap

Geographical data on interactive maps

Canvas

Custom visualizations with drag-and-drop elements

Dashboard List

List of dashboards matching criteria

Alert List

Active alerts and their states

Creating and Configuring Panels

Adding a Panel

1. Enter Edit Mode

   Click Add → Visualization or the + icon on an existing panel

2. Select Visualization

   Choose the visualization type from the picker

3. Configure Query

   Build your query using the data source query editor

4. Customize Options

   Adjust panel options, field config, and overrides

5. Apply Changes

   Click Apply to save the panel to the dashboard

Panel Editor Interface

The panel editor has three main sections:

interface PanelEditorLayout {
  visualization: {
    preview: PanelPreview;     // Live preview of panel
    controls: VisualizationPicker;
  };
  queryEditor: {
    tabs: ['Query', 'Transform', 'Alert'];  // Data pipeline tabs
    queries: DataQuery[];      // Query configurations
    transformations: DataTransformerConfig[];
  };
  optionsPane: {
    sections: [
      'Panel options',         // Title, description, links
      'Tooltip',              // Tooltip configuration
      'Legend',               // Legend settings
      'Graph styles',         // Visualization-specific
      'Standard options',     // Field config defaults
      'Overrides'            // Field-specific overrides
    ];
  };
}

Query Configuration

Panels can have multiple queries that are combined:

interface DataQuery {
  refId: string;              // Unique reference ID (A, B, C...)
  datasource?: DataSourceRef; // Optional datasource override
  hide?: boolean;             // Hide this query
  // ... datasource-specific query properties
}

// Example: Multiple queries in a panel
targets: [
  {
    refId: "A",
    expr: "rate(http_requests_total[5m])",
    legendFormat: "Requests/sec"
  },
  {
    refId: "B",
    expr: "rate(http_errors_total[5m])",
    legendFormat: "Errors/sec"
  }
]

Query Options

Control query behavior:

interface QueryOptions {
  maxDataPoints?: number;      // Maximum data points to return
  interval?: string;           // Minimum time interval (e.g., "1m")
  cacheTimeout?: string;       // Cache duration (e.g., "60")
  queryCachingTTL?: number;    // Query cache TTL in milliseconds
  timeFrom?: string;           // Panel time override (e.g., "now-1h")
  timeShift?: string;          // Shift time range (e.g., "1d")
  hideTimeOverride?: boolean;  // Hide time override indicator
}

Field Configuration

Field configuration controls how data is displayed:

interface FieldConfigSource {
  defaults: FieldConfig;       // Default config for all fields
  overrides: FieldConfigOverride[];  // Field-specific overrides
}

interface FieldConfig {
  unit?: string;               // Display unit (e.g., "bytes", "percent")
  decimals?: number;           // Decimal precision
  min?: number;                // Minimum value
  max?: number;                // Maximum value
  displayName?: string;        // Override field display name
  color?: FieldColor;          // Color configuration
  thresholds?: ThresholdsConfig;  // Threshold settings
  mappings?: ValueMapping[];   // Value mappings
  links?: DataLink[];          // Data links
  custom?: Record<string, any>;  // Visualization-specific config
}

Thresholds

Define color-coded thresholds:

interface ThresholdsConfig {
  mode: ThresholdsMode;  // 'absolute' or 'percentage'
  steps: Threshold[];    // Array of threshold steps
}

interface Threshold {
  value: number;         // Threshold value
  color: string;         // Color when value exceeds threshold
}

// Example
thresholds: {
  mode: 'absolute',
  steps: [
    { value: 0, color: 'green' },      // 0-80: green
    { value: 80, color: 'yellow' },    // 80-90: yellow
    { value: 90, color: 'red' }        // 90+: red
  ]
}

Value Mappings

Map values to text or colors:

interface ValueMapping {
  type: 'value' | 'range' | 'regex' | 'special';
  options: {
    match?: string | number;    // For 'value' type
    from?: number;              // For 'range' type
    to?: number;
    pattern?: string;           // For 'regex' type
    result: {
      text?: string;
      color?: string;
      icon?: string;
    };
  };
}

// Example: Map numeric status to text
mappings: [
  {
    type: 'value',
    options: {
      match: 1,
      result: { text: 'OK', color: 'green' }
    }
  },
  {
    type: 'value',
    options: {
      match: 0,
      result: { text: 'Failed', color: 'red' }
    }
  }
]

Data Transformations

Transform query results before visualization:

interface DataTransformerConfig {
  id: string;              // Transformer ID
  options: any;            // Transformer-specific options
  disabled?: boolean;      // Disable transformation
}

// Common transformations
transformations: [
  {
    id: 'filterFieldsByName',
    options: {
      include: { names: ['time', 'value'] }
    }
  },
  {
    id: 'calculateField',
    options: {
      mode: 'binary',
      reduce: { reducer: 'sum' },
      binary: {
        left: 'A',
        operator: '/',
        right: 'B'
      },
      alias: 'Ratio'
    }
  }
]

Common Transformations

Filter by Name

Include or exclude fields by name or regex pattern

Organize Fields

Reorder, rename, and hide fields

Join by Field

Combine multiple queries by a common field

Add Field from Calculation

Create calculated fields using math expressions

Group By

Group data by field values

Sort By

Sort data by field values

Reduce

Reduce multiple values to single values using aggregation

Series to Rows

Convert time series to row format

Panel Links

Add clickable links to panels:

interface DataLink {
  title: string;              // Link text
  url: string;                // URL with variable support
  targetBlank?: boolean;      // Open in new tab
  onClick?: Function;         // Custom click handler
}

// Example: Link to detailed dashboard
links: [
  {
    title: "View Details",
    url: "/d/xyz/${__field.name}?var-instance=${__field.labels.instance}",
    targetBlank: true
  }
]

Panel links support variable interpolation including ${__field.name}, ${__field.labels.labelname}, ${__value.raw}, and ${__value.text}.

Panel Repeating

Dynamically create panels based on variable values:

interface PanelRepeat {
  repeat?: string;            // Variable name to repeat by
  repeatDirection?: 'h' | 'v';  // Horizontal or vertical
  maxPerRow?: number;         // Max panels per row (horizontal only)
}

// Example: Create panel for each server
repeat: "server"              // Variable named "server"
repeatDirection: "h"          // Arrange horizontally
maxPerRow: 4                  // 4 panels per row

1. Create a Variable

   Add a multi-value variable in dashboard settings

2. Configure Panel Repeat

   In panel editor, go to Panel options → Repeat options

3. Select Variable

   Choose the variable to repeat by

4. Set Direction

   Choose horizontal or vertical layout

Panel Options

Each panel type has specific options. Common options include:

interface CommonPanelOptions {
  title?: string;             // Panel title
  description?: string;       // Panel description (tooltip)
  transparent?: boolean;      // Transparent background
  links?: DataLink[];         // Panel links
  
  // Common display options
  legend?: {
    show: boolean;
    placement: 'bottom' | 'right' | 'top';
    displayMode: 'list' | 'table';
    calcs: string[];          // Calculations to show
  };
  
  tooltip?: {
    mode: 'single' | 'multi' | 'none';
    sort: 'none' | 'asc' | 'desc';
  };
}

Best Practices

Follow these guidelines for effective panel design:

Query Optimization

• Use appropriate time ranges for your data frequency
• Set maxDataPoints to match panel width
• Enable query caching for expensive queries
• Use query interval hints: $__interval or $__rate_interval

Visual Design

• Keep panel titles clear and concise
• Use consistent color schemes across related panels
• Add descriptions for complex visualizations
• Choose appropriate visualization types for your data

Performance

• Limit the number of series per panel (aim for less than 50)
• Use transformations efficiently
• Avoid unnecessary field overrides
• Consider panel caching for static data

Advanced Features

Library Panels

Create reusable panels across dashboards:

interface LibraryPanel {
  uid: string;                // Library panel UID
  name: string;               // Panel name
  model: PanelModel;          // Panel configuration
  version: number;            // Version number
}

// Reference in dashboard
library Panel: {
  uid: "lib-panel-123",
  name: "CPU Usage Panel"
}

Panel Migration

Panels can define migration handlers:

interface PanelPlugin {
  onPanelMigration?: (panel: PanelModel) => Promise<Partial<PanelOptions>>;
  shouldMigrate?: (panel: PanelModel) => boolean;
}

// Automatically runs when pluginVersion changes

Next Steps

Dashboard Variables

Add dynamic filtering with variables

Templating

Use template syntax in queries and titles

Transformations

Learn about all available transformations

Sharing

Share individual panels or entire dashboards