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:

ParameterTypeDefaultDescription
elHTMLElement
string
Gauge element. HTMLElement or string with CSS selector of gauge element. Generated SVG will be inserted into this element
typestringcircleGauge type. Can be circle or semicircle
valuenumber0Gauge value/percentage. Must be a number between 0 and 1
sizenumber200Generated SVG image size (in px)
bgColorstringtransparentGauge background color. Can be any valid color string, e.g. #ff00ff, rgb(0,0,255), etc.
borderBgColorstring#eeeeeeMain border/stroke background color
borderColorstring#000000Main border/stroke color
borderWidthstring10Main border/stroke width
valueTextstringnullGauge value text (large text in the center of gauge)
valueTextColorstring#000000Value text color
valueFontSizestring31Value text font size
valueFontWeightstring500Value text font weight
labelTextstringnullGauge additional label text
labelTextColorstring#888888Label text color
labelFontSizestring14Label text font size
labelFontWeightstring400Label text font weight
onobjectObject 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.appLink to global app instance
gauge.elGauge HTML element
gauge.$elDom7 instance with gauge HTML element
gauge.gaugeSvgElGauge generated SVH HTML element
gauge.$gaugeSvgElDom7 instance with generated SVH HTML element
gauge.paramsGauge 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

EventTargetDescription
gauge:beforedestroyGauge 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.

EventArgumentsTargetDescription
beforeDestroy(gauge)gaugeEvent 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>