Gauge

This guide demonstrates how to use the Radzen Blazor Radial and Arc Gauge components.

Both gauge components are used to display a value (number) on a scale. The share similar configuration - only the way they display their value is different.

The Radial Gauge uses a pointer to “point” where the value is on the scale (similar to a watch). The Arc Gauge fills a portion of the scale with a color (similar to a progress bar).

Using the Radial Gauge in Radzen

Using the gauge componentes from Radzen is quite simple. You just need to drag and drop them and set (or data-bind) some properties.

1. Create a new page in an existing Radzen Blazor application.
2. Drag and drop a Radial Gauge component.
3. Expand the Scales section in the Property Grid. You will see that there is one scale already created for you.
4. Change any properties of the scale if needed - Min and Max or StartAngle and EndAngle.
5. Radial scales need at least one pointer. Click the … button next to the Pointers property. This opens the Pointers editor and allows you to add new pointers or configure the existing ones.
6. Set the Value property to a constant value e.g. 50 or data-bind it to an existing page property.

That’s it! Radzen will display a column chart in design time and use some mock data to simulate the runtime appearance.

Using the Arc Gauge in Radzen

Using the Arc Gauge is exactly the same. There is only one difference - the scale has a Values property instead of Pointers.

1. Create a new page in an existing Radzen Blazor application.
2. Drag and drop a Radial Arc component.
3. Expand the Scales section in the Property Grid. As with the Radial Gage there will be one scale already created for you.
4. Change any properties of the scale if needed - Min and Max or StartAngle and EndAngle.
5. Arc scales need at least one value. Click the … button next to the Values property. This opens the Values editor and allows you to add new values or configure the existing ones.
6. Set the Value property to a constant value e.g. 50 or data-bind it to an existing page property.

Using from code

Here is a very basic example that creates a Radial Gauge with minimal configuration.

<RadzenRadialGauge Style="width: 300px; height: 300px">
  <RadzenRadialGaugeScale>
    <RadzenRadialGaugeScalePoiner Value="50" />
  </RadzenRadialGaugeScale>
</RadzenRadialGauge>

The RadzenRadialGaugeScale tag is used to add a scale and configure its options - min and max value, start and end angle, tick display etc. the RadzenRadialGaugeScalePointer tag adds and configures a pointer of the RadialGaugeScale it is a child of. The key property here is Value - it specifies the value the pointer “points” to on the scale.

Here is an equivalent example of Arc Gauge.

<RadzenArcGauge Style="width: 300px; height: 300px">
  <RadzenArcGaugeScale>
    <RadzenArcGaugeScaleValue Value="50" />
  </RadzenArcGaugeScale>
</RadzenArcGauge>

The RadzenArcGaugeScale tag is used to add a scale and configure its options - min and max value, start and end angle, tick display etc. the RadzenArcGaugeScaleValue tag adds and configures a value of the ArcGaugeScale it is a child of.

Radzen Blazor gauges can have multiple scales and every scale can have multiple pointers or values.

Scale configuration

Min, max and step

By default the Min property of both scale types (Radial and Arc) is set to 0. Max is set to 100 and Step is set to 20.

To override the defaults use the Min, Max and Step properties of the RadzeRadialGaugeScale or RadzenArcGaugeScale tags.

<RadzenArcGauge Style="width: 300px; height: 300px">
  <RadzenArcGaugeScale Min="100" Max="1000" Step="100">
    <RadzenArcGaugeScaleValue Value="50" />
  </RadzenArcGaugeScale>
</RadzenArcGauge>

Tick configuration

By default the RadzenArcGaugeScale does not display ticks. You need to set the TickPosition property to GaugeTickPosition.Outside or GaugeTickPosition.Inside. To hide the ticks altogether use GaugeTickPosition.None.

<RadzenArcGauge Style="width: 300px; height: 300px">
  <RadzenArcGaugeScale TickPosition="GaugeTickPosition.Outside">
    <RadzenArcGaugeScaleValue Value="50" />
  </RadzenArcGaugeScale>
</RadzenArcGauge>

Minor ticks are not displayed by default. To display them set the MinorStep property to a value greater than 0.

<RadzenArcGauge Style="width: 300px; height: 300px">
  <RadzenArcGaugeScale TickPosition="GaugeTickPosition.Outside" MinorStep="5">
    <RadzenArcGaugeScaleValue Value="50" />
  </RadzenArcGaugeScale>
</RadzenArcGauge>

Change the start and and angles

By default the StartAngle property of the gauge scales is set to -90 and EndAngle is set to 90. This makes the default shape half a circle. Here is how to create a gauge which is a full circle:

<RadzenRadialGauge>
  <RadzenRadialGaugeScale StartAngle="0" EndAngle="360">
      <RadzenRadialGaugeScalePointer Value="50" />
  </RadzenRadialGaugeScale>
</RadzenRadialGauge>

Format the values

The scale ticks labels displays values with default formatting (ToString()). This can be customized in two ways - via the FormatString or the Formatter properties.

FormatString supports the standard .NET Number formats.

<RadzenRadialGauge Style="width: 300px; height: 300px">
  <RadzenRadialGaugeScale FormatString="{0:C}">
    <RadzenGaugeGaugeScalePointer Value="50" />
  </RadzenGaugeGaugeScale>
</RadzenGaugeGauge>

<RadzenRadialGauge Style="width: 300px; height: 300px">
  <RadzenRadialGaugeScale Formatter=@(value => value.ToString())>
    <RadzenGaugeGaugeScalePointer Value="50" />
  </RadzenGaugeGaugeScale>
</RadzenGaugeGauge>

Change the scale position

You can use the X and Y property of the scales to change the position of their center. Both properties have a default value of 0.5 which means that by default the center of a scale is the middle of the gauge. X and Y are a multiplier of the width and height.

For example you can move the center of the scale to the bottom of the component by setting Y to 1.

<RadzenRadialGauge Style="width: 300px; height: 300px">
  <RadzenRadialGaugeScale Y="1">
    <RadzenGaugeGaugeScalePointer Value="50" />
  </RadzenGaugeGaugeScale>
</RadzenGaugeGauge>

Using X and Y is also useful when you have multiple scales - this allows you to prevent them from overlapping which they will do by default.

Change the scale radius

By default the radius is set to be half the size of the Gauge - the smaller of its pixel width or height. You can tweak that by setting the Radius property. It is also a multiplier - the value you specify is multiplied by the initial value (half the width or height depending on which is smaller). The reason Radius is a multiplier and not an absolute value is responsiveness - users of smaller devices would expect to see a scale which is proportionally the same.

Here is how to make a scale twice as small

<RadzenRadialGauge Style="width: 300px; height: 300px">
  <RadzenRadialGaugeScale Radius="0.5">
    <RadzenGaugeGaugeScalePointer Value="50" />
  </RadzenGaugeGaugeScale>
</RadzenGaugeGauge>

Ranges

The RadzenRadialGaugeScale supports ranges. A range applies a color between two values of the scale. For example this is often used to specify a “dangerous” zone of the scale which a pointer isn’t supposed to go to. A RadzenRadialGaugeScale can have multiple ranges that should not overlap.

<RadzenRadialGauge>
  <RadzenRadialGaugeScale Min="0" Max="260">
    <RadzenRadialGaugeScalePointer Value="50" />
    <RadzenRadialGaugeScaleRange From="0" To="90" Fill="green" />
    <RadzenRadialGaugeScaleRange From="90" To="140" Fill="orange" />
    <RadzenRadialGaugeScaleRange From="140" To="260" Fill="red" />
  </RadzenRadialGaugeScale>
</RadzenRadialGauge>

Radial Gauge pointer configuration

Pointer length

By default a RadialGaugeScalePointer is as long as the radius of its scale. You can controll that via the Length property which is a multiplier with a default value 1.

Here is how to make the pointer half the radius:

<RadzenRadialGauge>
  <RadzenRadialGaugeScale>
    <RadzenRadialGaugeScalePointer Value="50" Length="0.5" />
  </RadzenRadialGaugeScale>
</RadzenRadialGauge>

Hide the pointer value

By default the Value property is displayed below the pointer. You can hide it by setting the ShowValue property to false.

<RadzenRadialGauge>
  <RadzenRadialGaugeScale>
    <RadzenRadialGaugeScalePointer Value="50" ShowValue="false" />
  </RadzenRadialGaugeScale>
</RadzenRadialGauge>

Customize the value display

Use the Template property of the pointer to tweak the default value appearance.

<RadzenRadialGauge>
  <RadzenRadialGaugeScale Min="0" Max="260">
    <RadzenRadialGaugeScalePointer Value=@value>
      <Template Context="pointer">
        <h4>
            @pointer.Value <sup>km/h</sup>
        </h4>
      </Template>
    </RadzenRadialGaugeScalePointer>
  </RadzenRadialGaugeScale>
</RadzenRadialGauge>

Arc Gauge value configuration

Hide the value

By default the Value property is displayed below the scale. You can hide it by setting the ShowValue property to false.

<RadzenArcGauge>
  <RadzenArcGaugeScale>
    <RadzenArcGaugeScaleValue Value="50" ShowValue="false" />
  </RadzenArcGaugeScale>
</RadzenArcGauge>

Customize the value display

Use the Template property of the pointer to tweak the default value appearance.

<RadzenArcGauge>
  <RadzenArcGaugeScale Min="0" Max="260">
    <RadzenArcGaugeScaleValue Value=@value>
      <Template Context="value">
        <h4>
            @value.Value <sup>km/h</sup>
        </h4>
      </Template>
    </RadzenArcGaugeScaleValue>
  </RadzenArcGaugeScale>
</RadzenArcGauge>

API

RadzenRadialGauge

RadzenRadialGaugeScale

RadzenRadialGaugeScalePointer

RadzenRadialGaugeScaleRange

RadzenArcGauge

RadzenArcGaugeScale

RadzenArcGaugeScaleValue