Skip to main content

Gauge Chart

The Gauge Chart displays a numeric value in relation to defined range boundaries using a semicircular arc with a positional indicator, similar to a speedometer. This chart type helps you visualize single metrics against targets, thresholds, or performance zones with customizable colors and flexible range configurations.

image-400 image-400

The Gauge Chart supports dynamic and manual range definitions, customizable value formatting, value name display, flexible arc sizes, and responsive sizing for various dashboard layouts.

Key Features​

  • Flexible Range Configuration:
    • Dynamic Ranges: Define ranges from query data (up to 10 boundaries)
    • Manual Ranges: Configure static ranges with custom thresholds
    • Color Coding: Assign distinct colors to each range for visual clarity
  • Value Display Options:
    • Value Label: Show formatted numeric value in the center
    • Value Name: Display metric name or custom label
    • Flexible Formatting: Number, money, percentage, or bytes formats
  • Arc Size Options: Choose between 240° or 140° gauge arcs
  • Customizable Labels: Configurable range boundary labels with size presets (S, M, L, XL)
  • Advanced Formatting: Precision control, abbreviation, currency symbols, and more
  • Responsive Design: Adapts to different container sizes with dynamic font scaling

Data Requirements​

The gauge chart requires query results with exactly one row of data:

  • Minimum: 1 column with a numerical value (the "gauge value")
  • Optional: Up to 10 additional numerical columns for dynamic range boundaries

Basic Gauge (Single Value)​

When using manual ranges, your query needs only one column with the current value:

SELECT
  current_sales  -- The gauge value
FROM metrics
WHERE metric_date = CURRENT_DATE

Example Result:

current_sales
85.7

With manual ranges, you configure all range boundaries directly in the chart settings. This is ideal for static thresholds that don't change (e.g., 0-30 = Poor, 30-70 = Good, 70-100 = Excellent).

Gauge with Dynamic Ranges​

When using dynamic ranges from query, include up to 10 additional numerical columns to define range boundaries. These extra columns are read left-to-right to determine where each range starts:

SELECT
  current_sales,  -- Column 1: The gauge value (required)
  0 as min_range, -- Column 2: Lower bound of first range
  50 as warn_low, -- Column 3: Lower bound of second range
  75 as target,   -- Column 4: Lower bound of third range
  100 as max      -- Column 5: Upper bound of last range
FROM metrics
WHERE metric_date = CURRENT_DATE

How Dynamic Ranges Work:

  • Column 1 (first column): The gauge value that the needle points to
  • Column 2 (second column): Lower bound of the first range
  • Column 3 (third column): Lower bound of the second range (and upper bound of the first range)
  • Column 4 (fourth column): Lower bound of the third range (and upper bound of the second range)
  • Column N (additional columns): Define subsequent range boundaries
  • The ranges are always continuous - each boundary value serves as both the end of one range and the start of the next

Example Result:

valuebound1bound2bound3bound4
10102030

This creates three ranges:

  • Range 1: 0 to 10 (columns 2 to 3)
  • Range 2: 10 to 20 (columns 3 to 4)
  • Range 3: 20 to 30 (columns 4 to 5)

The gauge value of 1 falls within the first range (0-10), and produces a gauge chart that looks as follows (with the default configuration):

image-400 image-400

Use Cases for Dynamic Ranges:

  • Performance metrics with targets that vary by time period or segment
  • KPIs where thresholds are calculated from historical percentiles
  • Metrics with ranges defined in a separate configuration table
  • Multi-tenant applications where each customer has different threshold values

Interactive Features​

A gauge chart is non-interactive and serves as a visual indicator for displaying current status or performance against defined thresholds.

Configuration​

The following configuration options are available on a gauge chart:

Gauge chart config Gauge chart config

Basic Settings​

Arc Size:

  • 240°: Wide semicircular arc spanning 240 degrees (default)
  • 140°: Narrower arc spanning 140 degrees for compact layouts

Value Display:

  • Show Value: Toggle display of the current gauge value in the center of the gauge
  • Show Name: Toggle display of the metric name above the value (or centered when Show Value is disabled)
  • Show Axis Labels: Toggle display of the range boundary labels on the gauge arc

Axis Label Size: Choose from preset size options for the range boundary labels when Show Axis Labels is enabled:

  • S (Small)
  • M (Medium)
  • L (Large)
  • XL (Extra Large)

Range Configuration​

The ranges of a gauge chart can either be dynamic (defined by the query result row) or static (manually configured).

Dynamic Ranges​

To use dynamic ranges, select From query in the gauge chart configuration.

image-400 image-400

Data Structure:

  • The first column is the gauge value
  • The second column marks the lower bound of the first range
  • The third column marks the lower bound of the second range
  • Additional columns (up to 10 total boundaries) define subsequent range boundaries
  • The ranges are always continuous

Color Customization:

  • Click on the colored square next to each range to change its color
  • Each range can use a different color for clear visual distinction

Use Cases:

  • Performance metrics with dynamic targets from a targets table
  • KPIs with thresholds that change based on business rules
  • Metrics where ranges are calculated based on historical data

Manual Ranges​

To use manually configured ranges, select Manual in the gauge chart configuration.

image-400 image-400

Data Requirements:

  • The SQL query should produce a single value, which is the current gauge value at time of query execution
  • All range boundaries are configured directly in the chart settings

Configuration:

  • Add ranges by clicking the Add Range button
  • Set the From and To values for each range
  • Click on the colored square to assign colors to each range
  • Remove ranges using the delete icon

Best Practices:

  • It is generally desirable, but not mandatory, for the ranges to be continuous (i.e., the upper bound of one range should equal the lower bound of the next range)
  • Define ranges that align with your business logic (e.g., 0-30 = Poor, 30-70 = Good, 70-100 = Excellent)

Value Formatting​

The Gauge Chart provides comprehensive formatting options for the displayed value:

image-400 image-400

Format Types:

  • Number: Standard numerical formatting with precision control
  • Money: Currency formatting with symbol and position
  • Percentage: Percentage display (automatically multiplies by 100)
  • Bytes: File size formatting (KB, MB, GB, etc.)

Number Formatting Options:

  • Precision: Number of decimal places (0-10)
  • Rounding: Enable/disable rounding
  • Abbreviation: Use K, M, B suffixes for large numbers
  • Thousands Separator: Add commas for readability (when not abbreviated)

Money Formatting Options:

  • Currency Symbol: Custom currency symbol (€, $, £, ¥, etc.)
  • Currency Position: Before or after the value
  • Precision: Decimal places for currency values
  • Abbreviation: Support for large amounts (e.g., $1.5M)

Percentage Formatting:

  • Automatically multiplies decimal values by 100
  • Adds the % symbol
  • Supports precision control

Bytes Formatting:

  • Automatic unit selection (B, KB, MB, GB, TB)
  • Binary (KiB) or decimal (KB) calculation modes
  • Precision control for displayed values

Value Name Display​

When Value name is enabled, the gauge displays a label for your metric. By default, it uses the humanized column name from your query (e.g., conversion_rate becomes "Conversion Rate"), but you can easily customize this in the configuration.

image-400 image-400

Customization:

  • Open the Customize tab in the chart configuration
  • Edit the Custom Name field to change the displayed label
  • Leave it empty to use the default humanized column name

Display Behavior:

  • With Value Label: Name appears above the value with semi-bold styling
  • Without Value Label: Name appears centered in large, bold styling (similar to value display)
  • Dynamic Sizing: Font size automatically adjusts based on text length to prevent overflow

Use Cases:

  • Display metric names like "Conversion Rate", "Monthly Revenue", "Customer Satisfaction"
  • Provide context when multiple gauges are displayed together
  • Show units or targets (e.g., "Sales Target", "Response Time (ms)")

Axis Label Formatting​

Range boundary labels on the gauge arc are automatically formatted using the same format settings as the value label:

  • Consistent Formatting: Axis labels use the same format, currency symbol, and precision as the center value
  • Smart Suppression: When value label is shown in the center, the exact matching value is hidden from the dial to avoid duplication
  • Money Format Optimization: Trailing zeros are suppressed for cleaner axis labels (e.g., "$100" instead of "$100.00")
  • Responsive Sizing: Labels adjust size based on available space and gauge dimensions
  • Color Distinction: Current value on dial uses darker/more prominent color when center label is hidden

Best Practices​

Data Preparation​

  • Single Row Results: Ensure your query returns exactly one row for the gauge to display
  • Appropriate Precision: Use database rounding in queries when displaying large numbers with abbreviation
  • Named Columns: Use meaningful column aliases (e.g., AS conversion_rate) for automatic value name display
  • Range Ordering: When using dynamic ranges, ensure boundary columns are ordered left to right from lowest to highest

Range Configuration​

  • Continuous Ranges: Make ranges continuous for intuitive visual interpretation (end of one range = start of next)
  • Meaningful Boundaries: Set thresholds that align with business logic and performance targets
  • Color Psychology: Use intuitive colors (red for poor, yellow for warning, green for good)
  • Balanced Zones: Avoid ranges that are too small or too large relative to the total gauge span

Visual Design​

  • Value Display: Enable value label for precise reading; disable for cleaner, more abstract visual indicators
  • Arc Selection: Use 240° for prominent dashboard elements, 140° for compact widgets or multi-gauge layouts
  • Label Sizing: Choose label size (S/M/L/XL) based on gauge size and dashboard density
  • Value Name Usage: Enable value name when multiple gauges are displayed to provide context

Formatting Strategy​

  • Consistent Units: Use the same format across related gauges (all percentages or all currency)
  • Appropriate Precision: Balance detail with readability (typically 0-2 decimal places)
  • Abbreviation: Enable for large numbers to maintain clean visual appearance
  • Currency Display: Include currency symbols for financial metrics to avoid confusion

Dashboard Integration​

  • Container Sizing: Provide adequate space for gauge to render clearly (minimum 200x200px recommended)
  • Grouping: Place related gauges together (e.g., all sales metrics, all operational metrics)
  • Complementary Charts: Pair with trend lines or tables showing historical data for context
  • Mobile Considerations: Test gauge visibility on smaller screens, consider 140° arc for mobile-optimized dashboards