Gauge

    Framework7 comes with Gauge component. It produces nice looking fully responsive SVG gauges.

    Gauge Layout

    Because Gauge SVG is generated by JavaScript its HTML layout is as simple as possible:

    <!-- Gauge element -->
    <div class="gauge"></div>

    Gauge App Methods

    Now we need to create/initialize the Gauge. Let's look at related App methods to work with Gauge:

    app.gauge.create(parameters)- create Gauge instance

    • parameters - object. Object with gauge parameters

    Method returns created Gauge's instance

    app.gauge.destroy(el)- destroy Gauge instance

    • el - HTMLElement or string (with CSS Selector) or object. Gauge element or Gauge instance to destroy.

    app.gauge.get(el)- get Gauge instance by HTML element

    • el - HTMLElement or string (with CSS Selector). Gauge element.

    Method returns Gauge's instance

    app.gauge.update(parameters)- update/rerender Gauge SVG according to passed parameters

    • parameters - object. Object with gauge parameters

    Method returns gauge value

    Gauge Parameters

    Now let's look at list of available parameters we need to create Gauge:

    Parameter Type Default Description
    el HTMLElement
    string
    Gauge element. HTMLElement or string with CSS selector of gauge element. Generated SVG will be inserted into this element
    type string circle Gauge type. Can be circle or semicircle
    value number 0 Gauge value/percentage. Must be a number between 0 and 1
    size number 200 Generated SVG image size (in px)
    bgColor string transparent Gauge background color. Can be any valid color string, e.g. #ff00ff, rgb(0,0,255), etc.
    borderBgColor string #eeeeee Main border/stroke background color
    borderColor string #000000 Main border/stroke color
    borderWidth string 10 Main border/stroke width
    valueText string null Gauge value text (large text in the center of gauge)
    valueTextColor string #000000 Value text color
    valueFontSize string 31 Value text font size
    valueFontWeight string 500 Value text font weight
    labelText string null Gauge additional label text
    labelTextColor string #888888 Label text color
    labelFontSize string 14 Label text font size
    labelFontWeight string 400 Label text font weight
    on object Object with events handlers. For example:
    var gauge = app.gauge.create({
      el: '.gauge',
      value: 33,
      valueText: '33%',
      on: {
        beforeDestroy: function () {
          console.log('Gauge will be destroyed')
        }
      }
    })
    

    Gauge Methods & Properties

    So to create Gauge we have to call:

    var gauge = app.gauge.create({ /* parameters */ })

    After that we have its initialized instance (like gauge variable in example above) with useful methods and properties:

    Properties
    gauge.app Link to global app instance
    gauge.el Gauge HTML element
    gauge.$el Dom7 instance with gauge HTML element
    gauge.gaugeSvgEl Gauge generated SVH HTML element
    gauge.$gaugeSvgEl Dom7 instance with generated SVH HTML element
    gauge.params Gauge parameters
    Methods
    gauge.update(parameters) Update/rerender gauge SVG element according to passed parameters. It accepts object with same parameters required for gauge initialization. You can pass only parameters that needs to be updated, e.g.
    var gauge = app.gauge.create({
      value: 0.5,
      // ...
    });
    
    // and when we need to update rendered SVG based on new value:
    gauge.update({
      value: 0.6,
    });
    gauge.destroy() Destroys gauge instance
    gauge.on(event, handler) Add event handler
    gauge.once(event, handler) Add event handler that will be removed after it was fired
    gauge.off(event, handler) Remove event handler
    gauge.off(event) Remove all handlers for specified event
    gauge.emit(event, ...args) Fire event on instance

    Gauge Events

    Gauge will fire the following DOM events on gauge element and events on app and gauge instance:

    DOM Events

    Event Target Description
    gauge:beforedestroy Gauge Element<div class="gauge"> Event will be triggered right before Gauge instance will be destroyed

    App and Gauge Instance Events

    Gauge instance emits events on both self instance and app instance. App instance events has same names prefixed with gauge.

    Event Arguments Target Description
    beforeDestroy (gauge) gauge Event will be triggered right before Gauge instance will be destroyed. As an argument event handler receives Gauge instance
    gaugeBeforeDestroy (gauge) app

    Gauge Auto Initialization

    If you don't need to use Gauge API and your Gauge is inside of the page and presented in DOM on moment of page initialization then it can be auto initialized with just adding additional gauge-init class, and specifying all parameters with data- attributes:

    <!-- Add gauge-init class, and specify parameters in data- attributes -->
    <div
      class="gauge gauge-init my-gauge"
      data-type="circle"
      data-value="0.44"
      data-value-text="44%"
      data-value-text-color="#ff9800"
      data-border-color="#ff9800"
    ></div>

    In this case if you need to access automatically created Gauge instance you can use the app.gauge.get app method:

    var gauge = app.gauge.get('.my-gauge');
    
    gauge.update({
      value: 0.9,
    });
    

    Examples

    <div class="block block-strong text-align-center">
      <!-- we will init this gauge in JavaScript -->
      <div class="gauge demo-gauge"></div>
      <!-- buttons to change gauge value -->
      <p class="segmented segmented-raised">
        <a href="#" class="button" data-value="0">0%</a>
        <a href="#" class="button" data-value="25">25%</a>
        <a href="#" class="button" data-value="50">50%</a>
        <a href="#" class="button" data-value="75">75%</a>
        <a href="#" class="button" data-value="100">100%</a>
      </p>
    </div>
    // Init top demo gauge
    var demoGauge = app.gauge.create({
      el: '.demo-gauge',
      type: 'circle',
      value: 0.5,
      size: 250,
      borderColor: '#2196f3',
      borderWidth: 10,
      valueText: '50%',
      valueFontSize: 41,
      valueTextColor: '#2196f3',
      labelText: 'amount of something',
    });
    
    // Change demo gauge on button click
    $$('.button').on('click', function () {
      var value = $$(this).attr('data-value');
      demoGauge.update({
        value: value / 100,
        valueText: value + '%'
      });
    });
    <div class="block-title">Circle Gauges</div>
    <div class="block block-strong">
      <div class="row">
        <div class="col text-align-center">
          <div
            class="gauge gauge-init"
            data-type="circle"
            data-value="0.44"
            data-value-text="44%"
            data-value-text-color="#ff9800"
            data-border-color="#ff9800"
          ></div>
        </div>
        <div class="col text-align-center">
          <div
            class="gauge gauge-init"
            data-type="circle"
            data-value="0.12"
            data-value-text="$120"
            data-value-text-color="#4caf50"
            data-border-color="#4caf50"
            data-label-text="of $1000 budget"
            data-label-text-color="#f44336"
            data-label-font-weight="700"
          ></div>
        </div>
      </div>
    </div>
    <div class="block-title">Semicircle Gauges</div>
    <div class="block block-strong">
      <div class="row">
        <div class="col text-align-center">
          <div
            class="gauge gauge-init"
            data-type="semicircle"
            data-value="0.3"
            data-value-text="30%"
            data-value-text-color="#f44336"
            data-border-color="#f44336"
          ></div>
        </div>
        <div class="col text-align-center">
          <div
            class="gauge gauge-init"
            data-type="semicircle"
            data-value="0.5"
            data-value-text="30kg"
            data-value-text-color="#e91e63"
            data-border-color="#e91e63"
            data-label-text="of 60kg total"
            data-label-text-color="#333"
          ></div>
        </div>
      </div>
    </div>
    <div class="block-title">Customization</div>
    <div class="block block-strong">
      <div class="row">
        <div class="col text-align-center">
          <div
            class="gauge gauge-init"
            data-type="circle"
            data-value="0.35"
            data-value-text="35%"
            data-value-text-color="#4caf50"
            data-value-font-size="51"
            data-value-font-weight="700"
            data-border-width="20"
            data-border-color="#4caf50"
            data-border-bg-color="#ffeb3b"
            data-bg-color="#ffeb3b"
          ></div>
        </div>
        <div class="col text-align-center">
          <div
            class="gauge gauge-init"
            data-type="circle"
            data-value="0.67"
            data-value-text="$670"
            data-value-text-color="#000"
            data-border-color="#ff9800"
            data-label-text="of $1000 spent"
            data-label-text-color="#4caf50"
            data-label-font-weight="800"
            data-label-font-size="12"
            data-border-width="30"
          ></div>
        </div>
      </div>
      <br>
      <div class="row">
        <div class="col text-align-center">
          <div
            class="gauge gauge-init"
            data-type="semicircle"
            data-value="0.5"
            data-value-text="50%"
            data-value-text-color="#ffeb3b"
            data-value-font-size="41"
            data-value-font-weight="700"
            data-border-width="10"
            data-border-color="#ffeb3b"
            data-border-bg-color="transparent"
          ></div>
        </div>
        <div class="col text-align-center">
          <div
            class="gauge gauge-init"
            data-type="semicircle"
            data-value="0.77"
            data-border-color="#ff9800"
            data-label-text="$770 spent so far"
            data-label-text-color="#ff9800"
            data-label-font-weight="800"
            data-label-font-size="12"
            data-border-width="10"
          ></div>
        </div>
      </div>
    </div>