Free cookie consent management tool by TermsFeed Gauge Component (a!gaugeField)
Gauge Component
SAIL Design System guidance available for Gauges

What gets measured gets done. So measure what matters with gauges. Learn how to configure and display gauges on your interface designs so you can visualize progress on your most important goals and initiatives.

Function

a!gaugeField( label, labelPosition, instructions, helpTooltip, percentage, primaryText, secondaryText, color, size, align, accessibilityText, showWhen, tooltip, marginAbove, marginBelow )

Displays a completion percentage in a circular style similar to the Progress Bar. Best used for showing progress when there is a target value, such as the number of completed surveys out of 360 total surveys, or number of hired employees out of 20 total open positions.

See also:

Parameters

Name Keyword Types Description

Label

label

Text

Text to display as the field label.

Label Position

labelPosition

Text

Determines where the label appears. Valid values:

  • "ABOVE" (default) Displays the label above the component.
  • "ADJACENT" Displays the label to the left of the component.
  • "COLLAPSED" Hides the label. The label will still be read by screen readers; see accessibility considerations for more information.
  • "JUSTIFIED" Aligns the label alongside the component starting at the edge of the page.

Instructions

instructions

Text

Supplemental text about this field.

Help Tooltip

helpTooltip

Text

Displays a help icon with the specified text as a tooltip. The tooltip displays a maximum of 500 characters. The help icon does not show when the label position is "COLLAPSED".

Percentage

percentage

Number (Decimal)

Number to display between 0 and 100.

Primary Text

primaryText

Text

Optional text to display on the first line inside the gauge. Create using plain text, a!gaugeIcon(), a!gaugePercentage(), or a!gaugeFraction().

Secondary Text

secondaryText

Text

Optional text to display on the second line inside the gauge.

Color

color

Text

Determines the color. Access the percentage using fv!percentage. Valid values: Any valid hex color or "ACCENT" (default), "POSITIVE", "NEGATIVE", "WARN".

Size

size

Text

Determines the size of the gauge. Valid values: SMALL, MEDIUM (default), LARGE.

Align

align

Text

Determines alignment of the gauge. Valid values: START, CENTER (default), END.

Accessibility Text

accessibilityText

Text

Additional text to be announced by screen readers. Used only for accessibility; produces no visible change.

Visibility

showWhen

Boolean

Determines whether the component is displayed on the interface. When set to false, the component is hidden and is not evaluated. Default: true.

Tooltip

tooltip

Text

Text to display as a tooltip on the gauge.

Margin Above

marginAbove

Text

Determines how much space is added above the layout. Valid values: "NONE" (default), "EVEN_LESS", "LESS", "STANDARD", "MORE", "EVEN_MORE".

Margin Below

marginBelow

Text

Determines how much space is added below the layout. Valid values: "NONE", "EVEN_LESS", "LESS", "STANDARD" (default), "MORE", "EVEN_MORE".

Usage considerations

Using the percentage parameter

  • If the percentage value is negative or null, the gauge shows with 0% of the circle complete.
  • If the percentage value is greater than 100, the gauge shows with 100% of the circle complete.

Editing the gauge primary text

The gauge configuration pane contains a step-by-step designer to help you quickly try out all Primary Text formats. We recommend you use this designer to select the format that works best for your gauge. gif of editing the value in the middle of the gauge using design mode

Formatting primary text width and color

  • If custom primaryText or secondaryText does not fit within the gauge, it is truncated.
  • If the primaryText is formatted using a!gaugeIcon(), a!gaugePercentage(), or a!gaugeFraction(), it will resize to fit within the circle.
  • To conditionally set the color of the gauge, use fv!percentage as shown in the "Gauge Setting Color Based on Percentage" example below.

Examples

To experiment with examples, copy and paste the expression into an interface object.

Gauge showing fraction complete

Use the interactive editor below to test out your code:

Gauge showing percent complete

Use the interactive editor below to test out your code:

Gauge showing icon with secondary text

Use the interactive editor below to test out your code:

Gauge setting color based on percentage

Use the interactive editor below to test out your code:

Feature compatibility

The table below lists this SAIL component's compatibility with various features in Appian.
Feature Compatibility Note
Portals Compatible
Offline Mobile Compatible
Sync-Time Custom Record Fields Incompatible
Real-Time Custom Record Fields Incompatible

Custom record fields that evaluate in real time must be configured using one or more Custom Field functions.

Process Reports Incompatible

Cannot be used to configure a process report.

Process Events Incompatible

Cannot be used to configure a process event node, such as a start event or timer event.

The following patterns include usage of the Gauge Component.

Gauge Component

FEEDBACK