Dash Gauge Component

A responsive gauge component for Dash applications. This component creates a gauge chart with a needle that points to a value, similar to the one generated by react-gauge-component.

There is a Gauge component in dash-daq as well, but it wasn't flexible (and responsive) enough for my use case, hence built this using existing dash components!

Features

• Fully responsive (sizes in % of screen width and height)
  • Scales up when the browser window size increases
  • Scales down when the browser window size decreases
• Customizable color map for different value ranges
• Customizable needle color and thickness
• Option to show/hide the value as a label
• Customizable start and end angles
• Customizable min and max values

Installation

  pip install dash-gauge-component

Usage

import dash
from dash import html
from dash_gauge_component import Gauge

app = dash.Dash(__name__)

app.layout = html.Div([
    html.H1("Dash Gauge Component Example"),

    # Basic usage
    Gauge(
        id="gauge-1",
        value=75,
        width="50%",
        height="300px",
    ),

    # Advanced usage with custom colors
    Gauge(
        id="gauge-2",
        value=42,
        min_value=0,
        max_value=100,
        width="80%",
        height="400px",
        color_ranges=[
            {'min': 0, 'max': 25, 'color': '#FF0000'},  # Red
            {'min': 25, 'max': 75, 'color': '#FFFF00'},  # Yellow
            {'min': 75, 'max': 100, 'color': '#00FF00'},  # Green
        ],
        needle_color="#000000",
        needle_thickness=3.0,
        show_value=True,
        gauge_thickness=0.1,
    ),
])

if __name__ == '__main__':
    app.run_server(debug=True)

Examples

The project includes example applications that demonstrate various configurations of the gauge component:

  # Run the simple example with style options
  python examples/simple_plot.py

  # Run the multiple plots example
  python examples/multiple_plots.py

The simple_plot.py example demonstrates the new style options including:

• Value formatting (percentages, currency, custom text)
• Custom font styling (family, size, color)
• Tick label styling

Testing

The project uses pytest for unit testing. To run the tests:

  pytest tests/

Testing Responsiveness

To test the responsiveness of the gauge component, you can use the included responsive test script:

  python tests/test_responsive.py

This script demonstrates various sizing options:

• Percentage-based sizing
• Fixed pixel sizing
• Viewport-relative sizing (vw/vh)
• Container-relative sizing
• Dynamic value updates

When you run this script and open the browser, try:

1. Resizing the browser window to see how gauges scale up and down
2. Observing how the value text scales proportionally with the gauge
3. Watching the dynamic gauge to verify smooth updates and proper text scaling

Visual Testing

To test the visual aspects of the gauge component:

  python tests/test_visual.py

API Reference

Gauge Component

Property	Type	Default	Description
id	string	(required)	The ID of this component, used to identify dash components in callbacks
value	number	(required)	The value to display on the gauge
min_value	number	0	The minimum value of the gauge
max_value	number	100	The maximum value of the gauge
width	string	'100%'	The width of the gauge as a percentage of the container
height	string	'100%'	The height of the gauge as a percentage of the container
color_ranges	array	[{'min': min_value, 'max': max_value, 'color': '#1f77b4'}]	A list of dictionaries defining color ranges for the gauge
needle_color	string	'#000000'	The color of the needle
needle_thickness	number	2.0	The thickness of the needle as a percentage of the gauge radius
show_value	boolean	true	Whether to display the value as text
start_angle	number	225	The starting angle of the gauge in degrees (bottom left)
end_angle	number	-45	The ending angle of the gauge in degrees (bottom right)
gauge_thickness	number	0.1	The thickness of the gauge arc as a fraction of the radius
value_format	string	"{:.1f}"	Format string for the displayed value (e.g., "{:.0f}" for no decimal places, "{:.1f}%" for percentage)
font_family	string	"Arial, sans-serif"	Font family for the value text
font_size	number	16	Base font size for the value text
font_color	string	"rgba(0,0,0,0.8)"	Color for the value text
tick_font_size	number	10	Font size for the tick labels
tick_font_color	string	"rgba(0,0,0,0.7)"	Color for the tick labels

Sample screenshots

License

MIT