heymichaelp/svg-dial

A customizable, responsive UI dial.

svg-dial

A customizable, responsive SVG dial UI element.

Introduction

After becoming frustrated with the lack of flexibility and support of jQuery-knob, I decided to create my own SVG dial that allowed me to customize the look and feel of the dial.

Though this element is designed to be highly customizable, it doesn't deviate from the design structure of the notch in the bottom section, the dial, etc. However, colors, font styles, sizes, and some other items are all customizable.

This may fit your needs and asthetics, it may not.

Installation

This package is available for installation via npm and bower

$ npm install svg-dial

$ bower install svg-dial

Usage

The only dependency this library has is on Snap.svg. It assumes this library is available to the module, and is configured to look for it in the AMD, CommonJS (Browserify) and global environments.

CommonJS (Browserify)

var SVGDial = require('svg-dial');

new SVGDial(document.getElementById('dial-container'), {
  onChange: function(percentage) {}
});

AMD

define(['svg-dial'], function(SVGDial) {
  new SVGDial(document.getElementById('dial-container'), {
    onChange: function(percentage) {}
  });
});

Global

...
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/snap.svg/0.3.0/snap.svg-min.js"></script>
<script type="text/javascript">
  new SVGDial(document.getElementById('dial-container'), {
    onChange: function(percentage) {}
  });
</script>
...

API

Constructor

new SVGDial(el, options);

el

Required: true
Type: HTMLElement, jQuery, String
Description: Can either be a DOM element, a jQuery object or a selector string.
Purpose: Identifies the target block element that the <svg> element will be build inside of.

options

Required: false
Type: Object
Description: The configuration options
Purpose: Defines default overrides and configuration options for the dial.

Configuration Options

Appearance/Functionality

disabled

Default: false
Type: Boolean
Purpose: If set to true, disables the manipulation of the dial.

frameBackgroundColor

Default: 'white'
Type: String
Description: Valid Hex or CSS color, or array of valid Hex or CSS colors to create a linear gradient
Purpose: Specifies the color of the frame (the rectangular container the dial is nested in)

frameSize

Default: 200
Type: Integer
Description: Number of pixels for both the width and height of the frame.
Purpose: Defines the size of the frame that the circular dial will be embedded in

ringBackgroundColor

Default: #888
Type: String, Array
Description: Valid Hex or CSS color, or array of valid Hex or CSS colors to create a linear gradient
Purpose: Specifies the color of the dial ring

innerBackgroundColor

Default: white
Type: String, Array
Description: Valid Hex or CSS color, or array of valid Hex or CSS colors to create a linear gradient
Purpose: Specifies the color of the inner circle and knob

fontFamily

Default: impact
Type: String
Description: Valid and available font family
Purpose: Uses this font family for the inner text that displays the percentage

fontSize

Default: 24
Type: Integer
Purpose: Uses this font size for the inner text that displays the percentage

fontStyle

Default: none
Type: String
Description: Valid and available font style
Purpose: Uses this font style for the inner text that displays the percentage

fontWeight

Default: none
Type: String
Description: Valid and available font weight
Purpose: Uses this font weight for the inner text that displays the percentage

Methods

onChange

Type: Function
Event: Any change in the dial setting during a drag.
Arguments:

• percentage: percentage between 0 and 1 that the dial is currently set at.

onStart

Type: Function
Event: The mouse down event on the dial
Arguments:

• percentage: percentage between 0 and 1 that the dial is currently set at.

onChange

Type: Function
Event: The mouse up event on the dial
Arguments:

• percentage: percentage between 0 and 1 that the dial is currently set at.

onReady

Type: Function
Event: The dial is loaded into the DOM
Arguments: none

Public API

config()

Type: Object
Description: Same structure as the options object.
Purpose: Overrides initial settings during runtime.

setValue()

Type: Integer
Description: Number between 0 and 1.
Purpose: Sets the value and position of the dial.

Contributing

svg-dial's Issues

Fix flexing drop shadow during rotation

This is due to the lerp calculation creating a larger drop shadow at 4/4 than at 0/8 and 8/0. Basically as the inner ring and knob rotate, the drop shadow has to rotate in an inverse direction so that it always appears at the bottom of the dial visually, even though it's moving around the dial. The drop shadow that is produced at 90 degree angles (e.g. the dial is at 0º, 90º, 180º), the shadow is at a 0x or 0y shift and 8x or 8y shift. When it's at 45º angles, the blur is at 4x or 4y, which creates a visually larger drop shadow.

setValue() does nothing if {disabled: true}

It should be possible to make changes to the value of the dial using setValue() while the it's disabled.

Right now I'm using something like

    var dial = new SVGDial('#svg-dial', {
      ringBackgroundColor: ['#f44', '#84c535'],
      frameBackgroundColor: 'white',
      frameSize: 400,
      ringWidth: 35,
      fontSize: 70
    });
    dial.setValue(0.3801169591);
    dial.config({disabled: true});

It would be preferable to use

    var dial = new SVGDial('#svg-dial', {
      ringBackgroundColor: ['#f44', '#84c535'],
      frameBackgroundColor: 'white',
      frameSize: 400,
      ringWidth: 35,
      fontSize: 70,
      disabled: true
    });
    dial.setValue(0.3801169591);

Color for area preceding dial knob

Option to include a colored fill for the area of the dial ring that precedes the dial knob position.