DOCSEARCHbyAlgolia
Submit Docs

JustGage Documentation

repository·master·Indexed 23 days ago

https://github.com/toorshia/justgage

JustGage is a high-performance JavaScript library for generating and animating clean, customizable SVG gauges. Rebuilt with modern ES6+ syntax and zero dependencies, version 2.0.1 features native SVG rendering, support for standard and donut-style gauges, and a comprehensive GaugeAnimator for smooth value transitions with various easing functions.

Tokens
4.5K
Snippets
5
Records
30
Agent score
83%

What's inside justgage

  2. Configure JustGage with defaults

    master
    When creating a configuration, you can provide a defaults object. If defaults is present in your configuration, JustGage will merge those values with your specific settings, allowing you to define a base style for multiple gauges and only override specific properties for individual instances.

  3. Create a gauge with the JustGage class

    master

    To create a gauge, import the JustGage class and instantiate it with a configuration object. The configuration object requires an id (the DOM element ID where the gauge will render), a value, and optionally min and max bounds.

    import { JustGage } from 'justgage';

const gauge = new JustGage({
  id: 'my-gauge',
  value: 75,
  min: 0,
  max: 100,
});

  4. Configure a JustGage instance

    master

    The JustGageConfig interface defines all available options for initializing and customizing a gauge. Key configuration categories include:

    • Container: Use id (string) or parentNode (HTMLElement) to specify where the gauge renders.
    • Value & Scale: Set value, min, max, decimals, and humanFriendly (for number formatting).
    • Visuals: Customize gaugeColor, width, height, label, title, and symbol.
    • Typography: Control colors and fonts for values (valueFontColor, valueFontFamily, etc.), labels, and titles.
    • Animation: Configure startAnimationTime, startAnimationType, refreshAnimationTime, and refreshAnimationType.
    • Gauge Types: Use donut: true for a donut gauge, or differential: true for a differential gauge.
    • Pointer: Enable a pointer with pointer: true and customize it via pointerOptions.
    • Sectors: Define color ranges using customSectors.

  5. Validation rules for JustGage configuration

    master

    The configuration object is validated during creation. The following rules must be met to avoid errors:

    1. Identification: Either id or parentNode must be provided.
    2. Range: The min value must be strictly less than the max value (min < max).
    3. Level Colors: levelColors must be a non-empty array. If it is invalid or empty, it will fallback to the default ['#a9d70b', '#f9c802', '#ff0000'].

  6. Calculate colors for gauges with getColor()

    master

    The getColor function determines the appropriate color for a gauge's current value based on a color array, a percentage, and optional custom sector configurations.

    It supports two modes:

    1. Gradient Mode: Interpolates between colors in the col array based on the pct (0-1).
    2. Custom Sectors Mode: If custSec (CustomSectors) is provided with ranges, the function returns the specific color assigned to the range containing the value. If custSec.percents is true, the value is treated as a percentage (0-100) instead of a raw value.

    If noGradient is set to true, the function returns the discrete color from the array instead of an interpolated RGB value.

  7. Generate gauge paths with createGaugePath

    master

    The createGaugePath method is a complex utility used to generate the SVG path data required for different types of gauges (Standard, Donut, or Differential).

    Parameters

    • sectorPctOrValue: A number (absolute value) or an object { from: number, to: number } representing the sector range.
    • min / max: The gauge range boundaries.
    • widgetW / widgetH: The width and height of the gauge widget.
    • dx / dy: Offsets for the center point.
    • gaugeWidthScale: Scale factor for the gauge thickness.
    • donut (boolean): If true, generates a donut-style gauge.
    • isDiff (boolean): If true, generates a differential gauge.
    • isDiff (boolean): If true, generates a differential gauge.

    Behavior

    • Standard Gauge: Draws an arc based on the provided range.
    • Donut Gauge: Draws a closed ring sector.
    • Differential Gauge: Draws a specific arc shape optimized for differential visualization.

  8. Create SVG shapes with SVGRenderer

    master

    The SVGRenderer provides methods to create and append various SVG elements to the canvas. Each method returns an SVGElement instance, which allows for chained attribute setting.

    Available shape methods:

    • circle(cx, cy, radius)
    • rect(x, y, width, height)
    • path(pathData)
    • line(x1, y1, x2, y2)
    • text(x, y, content)
    • sector(cx, cy, r1, r2, startAngle, endAngle): Creates an arc/sector path.

  9. Update gauge appearance with update()

    master

    The update() method allows you to modify the gauge's visual properties without re-instantiating it. You can pass either a single option name and value, or an object containing multiple options.

    Supported options include:

    • valueFontColor: Hex color for the value text.
    • labelFontColor: Hex color for labels (min, max, and main label).
    • gaugeColor: The color of the gauge background.
    • levelColors: Array of colors for the value level.
    • targetLine: The value for the target line.
    • targetLineColor: Color of the target line.
    • targetLineWidth: Width of the target line.
    • symbol: A string suffix for the value (e.g., '%').
    • decimals: Number of decimal places for the value.
    • title: The gauge title text.
    • titleFontColor: Hex color for the title.
    • showSectorColors: Boolean to toggle between level colors and static sectors.

  10. Initialize a JustGage instance

    master

    To create a new gauge, instantiate the JustGage class with a configuration object. You must provide either an id of an existing DOM element or a parentNode DOM element. The gauge will render an animated SVG inside the specified container.

    Common configuration options include:

    • id: The ID of the HTML element to use as the container.
    • parentNode: An existing DOM node to use as the container.
    • value: The current numeric value of the gauge.
    • min: The minimum value of the gauge.
    • max: The maximum value of the gauge.
    • title: A string for the gauge title.
    • donut: Boolean; if true, renders a donut-style gauge.
    • levelColors: An array of hex colors for the value level.
    • customSectors: An object defining specific color ranges via ranges (e.g., { ranges: [{ lo: 0, hi: 50, color: '#green' }] }).
    // Basic usage
const gauge = new JustGage({
  id: 'my-gauge',
  value: 75,
  min: 0,
  max: 100,
  title: 'Performance'
});

// With custom colors and sectors
const colorGauge = new JustGage({
  id: 'color-gauge',
  value: 60,
  levelColors: ['#green', '#yellow', '#red'],
  customSectors: {
    ranges: [
      { lo: 0, hi: 50, color: '#green' },
      { lo: 50, hi: 100, color: '#red' }
    ]
  }
});

  11. Instantiate the SVGRenderer

    master

    The SVGRenderer class is used to manage the SVG canvas for gauge visualizations. It replaces the legacy RaphaelJS dependency with native browser SVG APIs. When initializing, you can provide a container element, dimensions, and an optional viewBox for precise coordinate control.

    If you provide a percentage string for width or height (e.g., '100%'), the renderer automatically sets preserveAspectRatio='xMidYMid meet' to enable responsive scaling.