Creating a Gauge in React

The beginning of our journey finds us in a Gauge.jsx file, with a simple functional React component.

Whenever we create a new <Gauge>, we'll be able to customize it with five props:

• 1.
  value is the current value. This defaults to 50,
• 2.
  min is the minimum value for our metric. This defaults to 0,
• 3.
  max is the maximum value for our metric. This defaults to 100,
• 4.
  label,
• 5.
  units,

Underneath our code, we'll show the output of our component.

Let's start by adding an <svg> component, with a nice pink border so we can see its dimensions.

As we can see, the default size of a <svg> component is 300 pixels wide by 150 pixels tall.

We want our gauge to be 9em wide. This will let our gauge scale with our text, so it will never look disproportionate with the labels that we'll add later.

We can think about the <svg> element as a telescope into another world. Our telescope defaults to a normal zoom level: one unit is the same as one pixel.

But we can zoom our telescope in or out. To set the zoom on our telescope, we'll use the viewBox property.

viewBox takes four arguments:

• x and y set the position of the top, left corner of our view box. Changing these values will pan our view.
• width and height set the number of "units" that are visible inside of our view box. Changing these values will zoom our view.

Let's see what different telescope settings would look like for a simple svg with a purple circle at [50, 50], with a radius of 40.

For our gauge, let's simplify our math and focus our telescope on a simple 2 by 1 grid:

If this doesn't make much sense yet, stay tuned and you'll start seeing the benefits very soon.

Alright, let's begin the next phase of our journey:

Drawing arcs in SVG is a complex feat, but we can use our trusty weapon d3.arc(), from the d3-shape library.

d3.arc() will create an arc generator. We can configure our arc generator by calling different methods on it.

Let's look at the parameters we want to use for our arc:

• 1.
  our arc's radius will start at 0.65 and end at 1, ending up 0.35 units wide
• 2.
  our arc will start at -Math.PI / 2 (one quarter turn counterclockwise), and extend to Math.PI / 2 (one quarter turn clockwise)
• 3.
  let's make our arc a bit friendlier, with a cornerRadius of 1,

To use our arc generator, we simply need to call it.

Let's see what that looks like for our gauge. To start, we'll create a grey background arc, to show the full range of our gauge.

Great! Calling an arc generator, with these settings spits out a string:

This incantation is a set of instructions that can be passed to an SVG <path> element.

In our render method, let's create a new <path> element and pass these magic words to the d attribute.

Perfect!

Note how our arc is perfectly centered in our <svg>. This is because d3.arc(), by default, centers the arc around [0, 0].

If we revisit our grid figure, we can see that the [0, 0] point is at the bottom, center of the viewBox. This perfectly frames the top half of our arc, which is the only part that we're interested in.

Now that we've drawn the background arc which represents the range of possible values, we'll want to draw the filled arc that shows the current value.

• 1.
  First, we need to know what percent of the possible values lie below our current value. For example, if our range was from 0 - 100, a value of 50 would be 50% through our possible range.
  
  We'll create a percentScale which transforms values into a percent (between 0 and 1).Our percentScale will use a scaleLinear from d3-scale.
• 2.
  Next, we need to know what angle our filled arc needs to fill until. Let's create an angleScale that maps a percent into our possible angles (remember these values from our backgroundArc's innerRadius and outerRadius?)
• 3.
  Wonderful! Now that we know the end angle, we can create the incantation for our filled arc's d attribute.
• 4.
  And lastly, let's summit that hill and draw our filled arc!

Perfect! Play around with the slider to see how our filled arc looks with different values.

Adding a gradient

One thing you might notice when playing with our gauge's value is that most states feel kind of... the same.

Let's reinforce how far the current value is to the left of right by filling our filled arc with a light-to-dark gradient.

• 1.
  First, we'll need a color scale from our lightest to our darkest color.
• 2.
  Next, we need an array of color values that we want our gradient to interpolate through. To create this, we can use our colorScale's .ticks() method to output an array of equally-spaced values across the output range.
  
  Let's see a toy example for a simple scale that maps 0 - 1 to the range 0 - 100:

  .ticks() example

  1.

  const scale = scaleLinear()

  2.

  .domain([0, 1])

  3.

  .range([0, 100])

  4.

  5.

  const ticks = scale.ticks()

  6.

  alert(ticks)

Now that we have our gradient's colors, we can apply them!

On the web, we might be used to using a simple background CSS gradient, but those won't work in SVG land. Let's see what we need to do instead.

• 1.
  First, we'll want to create a <defs> (ie. definitions) element. Everything inside of a <defs> element will not be rendered, but we can reference them elsewhere. This is great for elements that need to be defined before being used.
• 2.
  Next, we'll create a <linearGradient> element.
• 3.
  Our <linearGradient> won't render anything by itself, but we'll give it an id attribute to use as a handle to reference later.
• 4.
  To correctly position our gradient, we want to set its gradientUnits attribute. This attribute has two options:

  • userSpaceOnUse (the default), which uses the parent <svg> element's coordinate system (set in its viewBox)
  • objectBoundingBox, which uses the coordinate system from the element the gradient is applied to

  We'll set gradientUnits to userSpaceOnUse, which is the default, but it's nice to be explicit.
• 5.
  Now that we know that we're working in our usual coordinate space, let's look at our grid diagram:

  [-1, -1]

  [1, -1]

  [-1, 0]

  [1, 0]

  [0, -1]

  [0, 0]

  We want our gradient to stretch all the way across our arc, so we'll start at [-1, 0] and end at [1, 0].

Next, we'll need to create gradient stops, which tell the gradient where each color should fall. The gradient itself will do the hard work of blending between each of these colors.

• 1.
  To do this, we'll map over our gradientSteps array, grabbing each color and its index in the array
• 2.
  For each color, we'll create a <stop> element
• 3.
  React requires a key for the outmost elements in a loop, to distinguish between them and help with re-render decisions
• 4.
  We'll set each stopColor attribute as our color, and
• 5.
  set each offset attribute as the percent (0 - 100} through the gradient. We could create a scale to convert the index into a percent, but it's easier here to just divide the index by the maximum index (or, one less than the number of gradientSteps).
• 6.
  And at last, we can use our handle and set the fill attribute of our filled arc.

Helpful bits & bobs

Another contextual clue we can add to our gauge is a sense of what is a normal value. When a value is close to the middle of our range, we might want to know whether or not it's above the mid-point.

One simple solution would be to draw a <line> element across the middle of our gauge, splitting it in two horizontally. If we make this line the same color as the background of our page (white), we can prevent it from stealing too much visual attention.

Note that we drew our line from [0, -1] to [0, -0.65] to prevent it from extending below our arc, whose inner radius starts at 0.65.

We might also notice that the end of our filled arc can get a little lost, especially with the rounded corner. But this is supposed to be the main point of our diagram!

Let's add a bubble where our arc ends, to give it more visual importance.

• 1.
  First, we need to figure out the position of our bubble. We'll use our custom getCoordsOnArc() function (defined in the next bullet point!). We can pass it our value's angle and the distance from the center of our arc. This will be half the distance the inner radius (0.65) is from the outer radius (1).
• 2.
  At the bottom of our file, let's define our getCoordsOnArc() function. This is something I usually have lying around, because it comes in handy when doing radial layouts.
• 3.
  At last, we can draw our bubble! We'll create a <circle> element, setting its center ([cx, cy]) at our markerLocation. A radius (r) of 0.2 feels right (a little larger than the arc itself), and we'll give it a slight border (stroke) to make it pop a bit.
  
  We'll also want to set the fill to match the color of the filled arc's gradient. Even though the gradient is partially covered by the bubble, this double encoding of the value helps the user focus on our main message: how far through the range is our value? Play around with the sliders to see how the changing color feels.

Our last bob is a little arrow that points to our bubble. This is our third redundancy for the current value - might as well throw up a neon sign, am I right?

Maybe it's overkill, but the arrow has another benefit: it further emphasizes the visual metaphor to an analog gauge, like one you would find in a pilot's dashboard. Let's implement it, and see how we like it.

• 1.
  First, we'll create a new <path> element.
• 2.
  A monster appears! What is this long, complicated string?
  
  One trick I like to use is to draw a vector graphic in a design tool such as Adobe Illustrator or Figma, then export that graphic as an svg. Then I can open that svg file in my text editor and grab the code I want.
  
  In this case, I created our arrow in Figma, then grabbed the <path>'s d attribute and pasted it in here.
• 3.
  We can use the angle we computed before to rotate our arrow. We'll need to convert it from radians into degrees, since the default rotate unit is degrees.
  
  We also have a static transform to move our arrow left and up, to rotate around the middle dot, instead of our arrow's top, left corner.

The last details

Phew! That was quite a large hill to climb!

Now that we're happy with our gauge diagram, let's add in some context to surface the actual data to users. We'll add the current value, and two optional labels: the name of the metric, and the unit we're working in. I find it's good to have these prompts when creating a new Gauge.

This step might feel a little "Draw the rest of the owl". I won't walk through every single change, but feel free to go through all of the changes (highlighted), it's pretty straightforward!

Let's look at a few highlights, though.