> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://help.sigmacomputing.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://help.sigmacomputing.com/_mcp/server.

# Build a gauge chart

Gauge charts are typically used to display a measurable value against a radial scale. Create gauge charts to evaluate growth, assess performance, or track progress toward a goal.

This document details basic gauge chart requirements and introduces key properties and format options to help you enhance your workbook charts.

![Gauge chart with a teal fill from the minimum to a measurable value, an orange needle, and a target mark on a gray radial scale.](https://files.buildwithfern.com/sigma.docs.buildwithfern.com/cb78fc0541f52339e48569c93c5ba3419eecb6afe568da6cb6a0f08dde09edcd/assets/docs-images/fda7059-1.png)

Example use cases:

* **IT analytics**: Measure implementation completion (as a percentage) to track a project’s progress.
* **Manufacturing analytics**: Track machine uptime (as a percentage) to monitor equipment performance.
* **Customer experience (CX) analytics**: Measure the net promoter score (NPS) for individual stores or customer service teams to gain insight into customer engagement and loyalty.

## User requirements

The ability to create gauge charts and other charts requires the following:

* You must be assigned an [account type](/docs/account-type-and-license-overview) with the **Edit Workbook** and/or **Explore Workbook** permission enabled.
* You must be the workbook owner or be granted **Can explore** or **Can edit** [workbook permission](/docs/folder-and-document-permissions).

If you're granted **Can explore** access to the workbook, you can create and modify chart properties and formatting in **Explore** mode, but you cannot publish your changes.

## Workbook prerequisite

Before you can build a gauge chart, you must [add a new chart element and select a data source](/docs/create-a-data-element).

At the core of every chart is an underlying data table (derived from the data source) that supplies the information visualized by the chart. As you build a gauge chart, Sigma automatically aggregates the underlying data to calculate values for the chart properties. You can [view the underlying data table](/docs/view-underlying-data) while configuring the chart to see the unaggregated data.

## Basic gauge chart requirements

To display a gauge chart, configure the following properties in the <img src="https://sigma-docs-screenshots.s3.us-west-2.amazonaws.com/Icons/element-properties.svg" alt="" /> **Element properties** panel:

* **Chart**: chart type displayed in the workbook
* **Value**: source column that defines the measurable value
* **Minimum**: source column that defines the minimum gauge value
* **Maximum**: source column that defines the maximum gauge value

In a gauge chart, a single value is measured on a radial scale. The minimum and maximum values determine the range of the gauge and provide reference points for assessing the measurable value.

### Select the chart type

After you [add a new chart](/docs/create-a-data-element) to a workbook, select the chart type:

* In the **Chart** property, click the dropdown field and select **Gauge** from the list. ![New Visualization panel with the chart type dropdown open showing Bar, Single Value, Funnel, Gauge, and Map - Region options.](https://files.buildwithfern.com/sigma.docs.buildwithfern.com/3a9b04bbb1366ec46b4b4e42892c8b33cec3ba9e51939fbd290232dfe83b5dc6/assets/docs-images/f8b6c27-2.png)

You can also use this dropdown field to convert an existing chart to a different type. Sigma retains all property and format configurations shared by the initial and new type. Unshared properties and formatting are not saved or restored if you further convert the chart.

### Define the measurable value

Configure a source column to define the measurable value.

1. In the **Value** property, click <img src="https://sigma-docs-screenshots.s3.us-west-2.amazonaws.com/Icons/button-add.svg" alt="" /> **Add calculation** and select an option from the menu:

   * To aggregate the values of an existing column, search or scroll the **Aggregate column** list and select the preferred column name.

   * To apply a custom formula or constant value, select **New column** and enter the formula or value in the toolbar.

   * To count the number of rows in the data source, select **Row count**.

   You can also select or replace an existing column by dragging and dropping a column name from the **Columns** list to the **Value** property.

   ![New Gauge editor with the Value property + menu open, showing New column, Row count, and an Aggregate column search field with "nps" entered and Cust NPS highlighted.](https://files.buildwithfern.com/sigma.docs.buildwithfern.com/abca077b60e839529ed7c69d792e7c6e1e521eb4b05e95b3163c302d3ca8fc26/assets/docs-images/04ff93f-3.png)

2. \[optional] Control how the data is calculated and displayed in the chart:

   1. Hover over the source column name, then click the caret (<img src="https://sigma-docs-screenshots.s3.us-west-2.amazonaws.com/Icons/caret.svg" alt="" />) to open the column menu.
   2. Hover over any of the following items, then select the preferred option:
      * **Set aggregate** - Calculate the value based on the selected aggregation method.
      * **Transform** - Convert the column to the selected [data value type](/docs/data-types-and-formats).
      * **Format** - Display the data label in the selected format.

   ![Sum of Cust NPS column menu with Set aggregate expanded, showing Sum, Avg, Median, and Percentile options with Avg highlighted.](https://files.buildwithfern.com/sigma.docs.buildwithfern.com/29f5b5128913f239402b349ef2c344258d9aa45339f1879a8cbaf26fd086d5a1/assets/docs-images/614dfc9-4.png)

   You can also use the toolbar to change the aggregation method (using the formula) and data label format.

### Define the gauge range

Configure a source column to define the minimum and maximum gauge values.

1. In the **Minimum** property, click <img src="https://sigma-docs-screenshots.s3.us-west-2.amazonaws.com/Icons/button-add.svg" alt="" /> **Add calculation** and select an option from the menu:

   * To aggregate the values of an existing column, search or scroll the **Aggregate column** list and select the preferred column name.

   * To apply a custom formula or constant value, select **New column** and enter the formula or value in the toolbar.

   * To count the number of rows in the data source, select **Row count**.

   You can also select or replace an existing column by dragging and dropping a column name from the **Columns** list to the **Minimum** property.

   ![Minimum property + menu open in the New Gauge editor, showing New column, Row count, and an Aggregate column list with a search field.](https://files.buildwithfern.com/sigma.docs.buildwithfern.com/5473c010385a8c9711fca34eb3c02ca6c49aed0294d339f4208a1a4cfbf510a6/assets/docs-images/e1a3940-5.png)

   If you don't configure a value in the **Minimum** property, the value defaults to zero.

2. In the **Maximum** property, click <img src="https://sigma-docs-screenshots.s3.us-west-2.amazonaws.com/Icons/button-add.svg" alt="" /> **Add calculation** and select an option from the menu:

   * To aggregate the values of an existing column, search or scroll the **Aggregate column** list and select the preferred column name.

   * To apply a custom formula or constant value, select **New column** and enter the formula or value in the toolbar.

   * To count the number of rows in the data source, select **Row count**.

   You can also select or replace an existing column by dragging and dropping a column name from the Columns list to the Maximum property.

   ![Maximum property + menu open in the New Gauge editor with Minimum already set to Calc, showing New column, Row count, and an Aggregate column list.](https://files.buildwithfern.com/sigma.docs.buildwithfern.com/f208d94a2de2570079f39bb758174858702583dbd8abd56b12cea01e794cc472/assets/docs-images/8d82137-6.png)

3. \[optional] Sigma auto-generates source column names and chart titles to reflect the visualized data, but you can customize these fields as needed:

   * To rename a source column, double-click its name in the **Value**, **Minimum**, or **Maximum** property, then enter a new name. Changes to the **Value** property are reflected in the default chart title.

   * To edit the chart title, double-click the title in the chart, then enter a new title.

   Sigma auto-generates the default chart title only. Once the title is customized, it no longer reflects changes to the **Value** property.

   ![Avg Customer NPS gauge chart with Min = 0, the Maximum field being edited, and the gauge displaying 6.961585 on a scale of 0 to 10.](https://files.buildwithfern.com/sigma.docs.buildwithfern.com/e7147d97347a5695ceb5144cd7d6cdd8f1b932d88a2858815f80b0de97485021/assets/docs-images/3db1dc7-gauge_define-gauge-range_step-3.png)

## Advanced gauge chart properties and formatting

Sigma features various properties and format options that give you the flexibility to build detailed gauge charts.

The following sections introduce configurations that can enhance your charts and help you deliver specific insights with meaningful and actionable information.

### Configure target value

Configure a target value in the <img src="https://sigma-docs-screenshots.s3.us-west-2.amazonaws.com/Icons/element-properties.svg" alt="" /> **Element properties** > **Target** property to mark a goal or benchmark on the gauge. The **Target** property can be configured in the same way as the **Value**, **Minimum**, and **Maximum** properties.

![Avg Customer NPS gauge with Min = 0, Max = 10, and a Target value of 8.5 marked on the radial scale.](https://files.buildwithfern.com/sigma.docs.buildwithfern.com/e7ef9d637aea9d613f4232711ec85a118d7385a44e5cb33395ddcada4b1e3186/assets/docs-images/8c7263d-8.png)

### Configure chart colors

Configure chart colors in the <img src="https://files.buildwithfern.com/sigma.docs.buildwithfern.com/319d7b643b298f8191aa6d05cc3e84257f06c5468cb9b953b22f84025210ad56/assets/docs-images/3ecaa20-element-properties.svg" alt="" /> **Element properties** > **Color** property.

![Color property with the Single color option selected, a blue color swatch, Reset Color link, and + Add rule link.](https://files.buildwithfern.com/sigma.docs.buildwithfern.com/fbce6e8cfd8714a35b25fae72afb0047fb27e4073c22979a7a88c6e66c9c0e3e/assets/docs-images/5eba8c3-gauge_color.png)

<table>
  <tbody>
    <tr>
      <td class="header-col">
        Single color
      </td>

      <td>
        <p>Enter a hex code or select a color for the gauge fill (the area that extends from the minimum value to the measurable value).</p>

        <p><em>See <a href="#h_01GQ1BAWY2T97HMEMAEKRSW4N2" target="_self">Conditional Formatting</a> for information about adding formatting rules.</em></p>
      </td>

      <td>
        <img class="screen" alt="Gauge chart with a solid red fill from the minimum to the needle position and a gray unfilled area." src="https://sigma-docs-screenshots.s3.us-west-2.amazonaws.com/Workbooks/Visualizations/Build+a+Gauge+Chart/gauge_color_single-color.png" />
      </td>
    </tr>

    <tr>
      <td class="header-col">
        By scale
      </td>

      <td>
        Select a color scale to apply to the gauge.
      </td>

      <td>
        <img class="screen" alt="Gauge chart with a red-to-yellow-to-green color scale applied across the radial scale." src="https://sigma-docs-screenshots.s3.us-west-2.amazonaws.com/Workbooks/Visualizations/Build+a+Gauge+Chart/gauge_color_by-scale.png" />
      </td>
    </tr>
  </tbody>
</table>

### Add conditional formatting

When you select **Single color** in the <img src="https://files.buildwithfern.com/sigma.docs.buildwithfern.com/319d7b643b298f8191aa6d05cc3e84257f06c5468cb9b953b22f84025210ad56/assets/docs-images/19524bd-element-properties.svg" alt="" /> **Element properties** > **Color** property, you can configure formatting rules ( **+Add rule**) that determine the gauge fill or gauge scale color according to value- or percentage-based conditions.

By default, conditional formatting applies to the gauge fill color (representing the measurable value), but you can apply rules to the gauge scale by selecting the **Show color on gauge** checkbox. This option hides the gauge fill and conditionally formats segments of the gauge based on values or percentages along the radial scale.

Example:

![Color property with three conditional formatting rules for Total Revenue at percentages greater than 75%, 25%, and 0%, styled green, yellow, and red, with a Show color on gauge checkbox.](https://files.buildwithfern.com/sigma.docs.buildwithfern.com/b15616b19c2708a92e3c59244d110f099615f294886103dfeca476a0063b1b9e/assets/docs-images/3105cda-9.png)

<table>
  <tbody>
    <tr>
      <td class="header-col">
        Gauge fill

        <br />

        (checkbox cleared)
      </td>

      <td class="header-col">
        Gauge

        <br />

        <em>(checkbox selected)</em>
      </td>
    </tr>

    <tr>
      <td>
        <img class="screen" alt="Gauge chart with a yellow gauge fill and a gray unfilled area, with the Show color on gauge checkbox cleared." src="https://sigma-docs-screenshots.s3.us-west-2.amazonaws.com/Workbooks/Visualizations/Build+a+Gauge+Chart/gauge_color_conditional-formatting_show-color-on-gauge_cleared.png" />
      </td>

      <td>
        <img class="screen" alt="Gauge chart with the radial scale divided into red, yellow, and green segments, with the Show color on gauge checkbox selected." src="https://sigma-docs-screenshots.s3.us-west-2.amazonaws.com/Workbooks/Visualizations/Build+a+Gauge+Chart/gauge_color_conditional-formatting_show-color-on-gauge_selected.png" />
      </td>
    </tr>
  </tbody>
</table>

When the conditions of multiple rules are met, Sigma applies the formatting rules in order of precedence, from top to bottom. Drag and drop rule blocks to reorder them as needed.

When you create a value-based rule, Sigma evaluates the measure or gauge scale value. If the value meets the conditions defined in the **Formatting rule** fields, the color selected in the **Style** field applies to the gauge fill or gauge scale.

![Formatting rule configuration with Apply to set to Value, a Formatting rule dropdown set to Greater than, an empty value field, and a Style option.](https://files.buildwithfern.com/sigma.docs.buildwithfern.com/1cb1b020165ef6260fb5919cf351fbae2fd2d3dbf8d445c0a33861e650fa8af7/assets/docs-images/5a2fd2a-10.png)

Example:

![Color property with a conditional formatting rule applied to Metric where Value is greater than or equal to 300000, styled green.](https://files.buildwithfern.com/sigma.docs.buildwithfern.com/76c843233e621f48b73253ad6e9416fcac2e1fedbeec073c1e3710230812f062/assets/docs-images/ef07c2c-11.png)

<table>
  <tbody>
    <tr>
      <td class="header-col">
        Condition not met
      </td>

      <td class="header-col">
        Condition met
      </td>
    </tr>

    <tr>
      <td>
        <img class="screen" alt="Gauge chart ranging from \$0 to \$500k with a red fill and needle pointing to \$250k, indicating the value condition is not met." src="https://sigma-docs-screenshots.s3.us-west-2.amazonaws.com/Workbooks/Visualizations/Build+a+Gauge+Chart/gauge_conditional-formatting_value_not-met.png" />
      </td>

      <td>
        <img class="screen" alt="Gauge chart ranging from \$0 to \$500k with a green fill and needle pointing to \$325k, indicating the value condition is met." src="https://sigma-docs-screenshots.s3.us-west-2.amazonaws.com/Workbooks/Visualizations/Build+a+Gauge+Chart/gauge_conditional-formatting_value_met.png" />
      </td>
    </tr>
  </tbody>
</table>

When you create a percentage-based rule, Sigma evaluates the measure or gauge scale value relative (as a percentage) to the maximum or target value, depending on the rule configuration. If the percentage meets the conditions defined in the **Formatting rules** field, the color selected in the **Style** field applies to the gauge fill or gauge scale.

![Formatting rule configuration with Apply to set to Percentage, Compare value to set to Maximum, Formatting rule set to Greater than, and an empty percentage field.](https://files.buildwithfern.com/sigma.docs.buildwithfern.com/8ec895b29771299d57f8e98ccca0ce69d4fc6bd2bfd7ae88069dde4723f48c6a/assets/docs-images/28dd9bf-12.png)

Example:

![Color property with a conditional formatting rule applied to Metric where Percentage is greater than 50%, styled green.](https://files.buildwithfern.com/sigma.docs.buildwithfern.com/b46822e9a19405dfbbe364d9c3846f8a4643cbcf0a58e741f459014ec6ca93a2/assets/docs-images/5f072ee-13.png)

<table>
  <tbody>
    <tr>
      <td class="header-col">
        Condition not met
      </td>

      <td class="header-col">
        Condition met
      </td>
    </tr>

    <tr>
      <td>
        <img class="screen" alt="Gauge chart ranging from 0 to 100 with a red fill and needle pointing to 40, indicating the percentage condition is not met." src="https://sigma-docs-screenshots.s3.us-west-2.amazonaws.com/Workbooks/Visualizations/Build+a+Gauge+Chart/gauge_conditional-formatting_percentage_not-met.png" />
      </td>

      <td>
        <img class="screen" alt="Gauge chart ranging from 0 to 100 with a green fill and needle pointing to 60, indicating the percentage condition is met." src="https://sigma-docs-screenshots.s3.us-west-2.amazonaws.com/Workbooks/Visualizations/Build+a+Gauge+Chart/gauge_conditional-formatting_percentage_met.png" />
      </td>
    </tr>
  </tbody>
</table>

### Customize gauge marks

Customize gauge marks (gauge, needle, and target) in the <img src="https://sigma-docs-screenshots.s3.us-west-2.amazonaws.com/Icons/element-format.svg" alt="" /> **Element format** > **Gauge marks** section.

![Gauge marks section with options for Gauge color, Show needle checkbox selected, Needle color, Show gauge fill checkbox selected, and Target color.](https://files.buildwithfern.com/sigma.docs.buildwithfern.com/1319ad71af5659c54b7c8227916ba7430334e41efb9ab5472c6a51aa35404fbb/assets/docs-images/6262e83-14.png)

<table>
  <tbody>
    <tr>
      <td class="header-col">
        Gauge color
      </td>

      <td>
        <p>Enter a hex color code or select a standard color for the unfilled area of the gauge (extending from the end of the gauge fill to the maximum value).</p>

        <p><em><a href="#h_01GQ1BAWY2T97HMEMAEKRSW4N2" target="_self">Conditional formatting rules</a> take precedence over the <strong>Gauge color</strong> selection.</em></p>
      </td>

      <td>
        <img class="screen" alt="Gauge chart with an orange fill from the minimum to the needle position and a teal unfilled gauge color extending to the maximum." src="https://sigma-docs-screenshots.s3.us-west-2.amazonaws.com/Workbooks/Visualizations/Build+a+Gauge+Chart/gauge_gauge-marks_gauge-color.png" />
      </td>
    </tr>

    <tr>
      <td class="header-col">
        Show needle
      </td>

      <td>
        <p>Show or hide the needle that points to the measurable value in the gauge.</p>
      </td>

      <td>
        <img class="screen" alt="Gauge chart with an orange fill, a gray unfilled area, and a target mark, with the needle hidden." src="https://sigma-docs-screenshots.s3.us-west-2.amazonaws.com/Workbooks/Visualizations/Build+a+Gauge+Chart/gauge_gauge-marks_show-needle.png" />
      </td>
    </tr>

    <tr>
      <td class="header-col">
        Needle color
      </td>

      <td>
        <p>Enter a hex color code or select a standard color for the gauge needle.</p>
      </td>

      <td>
        <img class="screen" alt="Gauge chart with an orange fill, a gray unfilled area, a target mark, and a light blue needle." src="https://sigma-docs-screenshots.s3.us-west-2.amazonaws.com/Workbooks/Visualizations/Build+a+Gauge+Chart/gauge_gauge-marks_needle-color.png" />
      </td>
    </tr>

    <tr>
      <td class="header-col">
        Show gauge fill
      </td>

      <td>
        <p>Show or hide the gauge fill color.</p>

        <p><em>This field is unavailable when <a href="#h_01GQ1BAWY2T97HMEMAEKRSW4N2" target="_self">conditional formatting rules</a> exist and the <strong>Show color on gauge</strong> checkbox is selected (because the selection already hides the gauge fill).</em></p>
      </td>

      <td>
        <img class="screen" alt="Gauge chart with the gauge fill hidden, showing only a gray gauge with a black needle and a target mark." src="https://sigma-docs-screenshots.s3.us-west-2.amazonaws.com/Workbooks/Visualizations/Build+a+Gauge+Chart/gauge_gauge-marks_show-gauge-fill.png" />
      </td>
    </tr>

    <tr>
      <td class="header-col">
        Target color
      </td>

      <td>
        <p>Enter a hex color code or select a standard color for the target mark.</p>

        <p><em>This field is unavailable if a <a href="#h_01GQ6784X3ANGDWHZQAGSH0X38" target="_self">target value</a> is not configured in the <strong>Target</strong> property.</em></p>
      </td>

      <td>
        <img class="screen" alt="Gauge chart with an orange fill, a gray unfilled area, a black needle, and a red target mark." src="https://sigma-docs-screenshots.s3.us-west-2.amazonaws.com/Workbooks/Visualizations/Build+a+Gauge+Chart/gauge_gauge-marks_target-color.png" />
      </td>
    </tr>
  </tbody>
</table>

## All gauge chart format options

* [Element style](/docs/customize-chart-background-and-style)
* [Title](/docs/customize-element-title)
* [Data labels](/docs/display-chart-data-labels)
* [Gauge marks](/docs/build-a-gauge-chart)

## Related resources

* [Intro to charts](/docs/intro-to-visualizations)
* [Create a data element](/docs/create-a-data-element)