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:

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:

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 Events

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

DOM Events

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.

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>