Definition

The Gauge Widget in Zenphi dashboards is a powerful visual component designed to represent a numerical metric within a defined range, using a dynamic dial (or pointer) on a semi-circular or circular gauge. It provides an instant, intuitive understanding of a value's position within a target range, ideal for performance monitoring, thresholds, and benchmarks.

At its core, the Gauge Widget takes data from a Zenphi Table, applies a function (like count, sum, or average), and maps the resulting value onto a defined scale, typically from a minimum to maximum number. It also includes color-coded segments that visually communicate different levels (e.g., safe, warning, critical), making the data both actionable and engaging at a glance.

Key capabilities include:

• Mapping any calculated metric onto a defined numeric range
• Highlighting threshold zones with color-coded sections across the gauge
• Applying filters to display dynamic, user-specific, or conditional data
• Full styling options, including precision, prefix/suffix, and font control
• Seamless integration with other dashboard widgets for real-time reporting

Whether you're tracking system load, team progress, or budget utilization, the Gauge Widget makes complex data visually digestible and immediately actionable.

📌 Example Use Cases

1. Sales Target Achievement

Visualize how close the sales team is to reaching their monthly or quarterly sales target. The gauge can show the total sales value compared to a target, with color segments indicating performance levels (e.g., green = above 90%, yellow = 70–89%, red = below 70%).

2. Employee Performance Score

Display an individual employee’s average performance rating based on feedback forms. The widget dynamically shows the viewer’s own data, helping them track personal improvement over time.

3. Form Submission Completion Rate

Monitor how many users have submitted a required form (e.g., compliance, onboarding) out of the total expected. The gauge reflects the completion rate using a percentage function.

4. IT Incident Resolution SLA

Track the percentage of IT tickets resolved within SLA. A color-coded gauge instantly shows if the team is within acceptable performance thresholds.

5. Budget Consumption

Compare current budget spend versus total allocated budget. Gauge segments can be set to warn users visually when they approach or exceed spending limits.

6. Production Output vs. Goal

In manufacturing or operations, track actual production numbers against daily or weekly output goals. Helps supervisors instantly identify underperformance.

7. Customer Satisfaction Index

Display the average customer satisfaction score from recent surveys. The gauge reflects customer sentiment using segmented color bands for low, medium, and high satisfaction.

8. Capacity Utilization

Show how much of a service or resource is currently being utilized, like storage, seats, or bandwidth. Gauge changes color based on thresholds to prompt quick decisions.

9. Training Completion Progress

Track how much of a training program has been completed by a user or team. Especially useful for HR or onboarding workflows to ensure readiness before go-live.

10. Project Milestone Progress

Measure the completion level of a project phase or milestone. The gauge helps project managers communicate status quickly to stakeholders.

Configuration

Configuring the Gauge Widget in Zenphi allows you to convert raw table data into a visually powerful indicator that’s instantly readable and highly customizable. Here’s a breakdown of all the key configuration elements:

1. Data Source

The first step in setting up your gauge is selecting the Zenphi Table that holds the data you want to visualize.

• This table serves as the data backend for your gauge.
• All subsequent configurations like metrics, filters, and conditions will pull from this table.

📌

Example: If you're tracking team performance, your data source might be a table called “Sales Team KPIs” or “Weekly Task Logs”.

2. Gauge Data

This is where you define what data should be represented on the gauge and how it should be calculated.

Select Widget Data Field

• Choose a specific field (column) from the selected table that you want to measure or analyze.
• This field could be numerical (like revenue or time spent) or textual (like department or task type).

Select a Function

• Based on the data type of the selected field, Zenphi will present appropriate aggregation functions:

For number fields:

• Count – Total number of records
• Sum – Sum of the selected numeric field
• Average – Mean of the values
• Maximum / Minimum – Highest or lowest value in the field
• Median – Middle value
• Unique Count – Number of unique values in the field

For string fields:

• Count – Number of records
• Unique Count – Number of unique string values

🧠

Use Case: If you select the field "Monthly Sales" with the function “Sum,” the gauge will display the total sales value across all records (or filtered records if a filter is applied).

3. Range (Min / Max)

This sets the scale boundaries of your gauge:

• Minimum: The start of the gauge (typically zero, but can be adjusted to any number)
• Maximum: The end of the gauge – your top-end threshold

🧠

Use Case: You can set a range of 0 to 100000 if you're tracking budget consumption, or 0 to 10 if you're measuring customer satisfaction on a 10-point scale.

4. Axisline Colors (Threshold Visualization)

The Axisline defines how your gauge is visually segmented into zones using colors. This enables immediate visual interpretation of performance or risk level.

You can add multiple colored thresholds, each covering a percentage of the gauge's full range. The percentages determine how much of the gauge arc each color occupies.

Configuration Rules:

• The last color must always end at 100%.
• The percentages stack incrementally, and each defines the end point of its segment.

Example Axisline Color Configurations:

Example 1:

Result: Gauge is green from 0–50%, yellow from 51–75%, and red from 76–100%.

Example 2:

Result: Blue covers the first quarter, orange covers the next 35%, and purple covers the remaining 40%.

These color segments are extremely useful for:

• Setting performance thresholds (e.g., healthy vs. risky values)
• Guiding user decisions (e.g., showing red if a quota isn’t met)
• Creating executive-level dashboards that communicate at a glance

Appearance

The Gauge Widget’s appearance settings in Zenphi allow you to fine-tune the look, structure, and visual behavior of the widget to perfectly align with your dashboard’s design and clarity goals. Whether you're building a minimalist dashboard or a more analytic panel, these settings help deliver meaningful visuals with style.

📌 Widget Positioning and Border Style

• Floating in Dashboard Layout: Like all Zenphi dashboard widgets, the gauge floats within the flexible dashboard grid, allowing you to position and resize it freely.

• Show Widget Border?

  • Toggle ON to display a distinct border around the widget, visually grouping it like a section.
  • Toggle OFF for a cleaner look where the gauge blends seamlessly with the dashboard background.

🏷️ Title Customization

Each Gauge Widget supports two title areas:

1. Top Title

   • Controlled by the "Show Widget Title?" option.
   • Appears at the top of the widget.
   • Useful for labeling the metric (e.g., “Current Utilization”, “Quota Progress”).

2. Bottom Title

   • This title appears directly beneath the gauge value, often used to provide context or unit labeling (e.g., “Units Sold”, “Completion Rate”).

✍️ Value Formatting (Prefix, Suffix, Separators)

Under the Style section, you can personalize how the displayed value appears.

• Prefix & SuffixAdd static text before or after the value to provide meaning or units.

  Examples:

  • Value = 19
  • Prefix: "The amount is " → Displays: The amount is 19
  • Suffix: " kilos" → Displays: 19 kilos
  • Prefix + Suffix: "Progress: " & "%" → Displays: Progress: 19%

• Thousand Separator

  • Toggle ON to format large numbers with commas (e.g., 1,000,000)
  • Toggle OFF to show the raw number (e.g., 1000000)

This ensures readability especially for large financial or statistical metrics.

🧩 Gauge Design & Layout Settings

These visual elements allow you to shape the gauge's arc, pointer, and label structure.

🔄 Gauge Arc Angles

• Start Angle (Default: 180)Defines where the arc begins. 180 creates a half-circle from left to right.

• End Angle (Default: 0)Defines where the arc ends. 0 means the arc ends on the right side, completing the half-circle.

🔧

You can create custom arcs (e.g., quarter gauges or full circles) by changing these values (e.g., Start = 90, End = -270).

📍 Pointer Customization

• Pointer Length (0–100)

  • Defines how far the pointer reaches into the gauge radius.
  • 100 = Full length, touching the gauge border.
  • 50 = Half-length.

• Pointer Width (0–100)

  • Defines the thickness of the pointer.
  • Higher values make it bolder and more visible.

✨

Customizing the pointer makes the gauge more accessible in dense dashboards.

🧮 Gauge Label and Axis Styling

• Split Number

  • Controls the number of labeled segments on the gauge.
  • If the range is from 0 to 10 and you set split number to 10, the gauge shows 0, 1, 2, ..., 10.

• AxisLine Width (0–35)

  • Defines the thickness of the gauge arc.
  • Higher values make the gauge bolder and more prominent.

• AxisLabel Distance (-200 to 200)

  • Controls how far the labels sit from the center of the gauge.
  • -200: Labels are placed far from the center.
  • 200: Labels are closer to the center.

• AxisLabel Size (0–35)

  • Controls the font size of the gauge labels.
  • Use smaller sizes for compact dashboards or larger for focused visual emphasis.

🔍 Filter Conditions

The Filter Conditions feature allows you to dynamically control which data records from your selected table are used in calculating the gauge value. This is a powerful capability that enables you to personalize widgets, restrict data visibility, and ensure accurate metrics—especially when different users view the same dashboard.

🧠 How It Works

Filters are applied to the Data Source (your selected Zenphi Table), and only matching records are included in the aggregation function (Sum, Count, Average, etc.).

You can use a combination of AND / OR logic, define field-level conditions, and even personalize results based on current user tokens.

⚙️ Condition Structure

Each filter rule consists of:

1. Field – Choose a field/column from your selected table.

2. Operator – Choose one of the following comparison operators:

   • equal to
   • not equal to
   • contains
   • not contains
   • starts with
   • ends with
   • has none of (used with multi-select fields)
   • is null
   • is not null

3. Value – Set a hardcoded value, or use the Token Picker to insert a dynamic user-specific value (like current user email, ID, or role).

👤 Using Tokens for Personalization

The Token Picker allows you to filter records based on who is viewing the dashboard.

Available tokens include:

• {{user.email}} – current user's email
• {{user.name}} – current user's full name
• {{user.id}} – internal user ID
• {{user.isAdmin}} – boolean indicating admin role
• Any custom user attributes configured in Zenphi

This enables row-level security and user-based customization of your dashboards.

✅ Examples

1. Filter records assigned to the logged-in user

Condition:

• Field: Assigned To
• Operator: equal to
• Value: {{user.email}}

Use case:Show a gauge displaying total tasks assigned to the person currently viewing the dashboard.

2. Show records only with status "Completed"

Condition:

• Field: Status
• Operator: equal to
• Value: Completed

Use case:Gauge shows the count or percentage of completed tasks across the organization.

3. Filter items within a numeric range

Conditions:

• Field: Score
• Operator: greater than or equal to
• Value: 80AND
• Field: Score
• Operator: less than
• Value: 100

Use case:Display the number of high-scoring records, e.g., test results or survey ratings.

4. Only show records for Admins

Condition:

• Field: Role
• Operator: equal to
• Value: AdminOR
• Token: {{user.isAdmin}}
• Operator: equal to
• Value: true

Use case:Gauge widget should only show data to admins, or show different aggregate values based on role.

5. Show only recent entries (Last 30 days)

Condition:

• Field: Created Date
• Operator: greater than or equal to
• Value: {{today - 30}} (or use date picker depending on UI)

Use case:Show a gauge metric for activity in the last month, such as total submissions or user logins.

🎯 Example Scenario: Show Each Employee Their Performance Score

Goal

You want to create a dashboard where each employee can log in and see only their own performance score using a Gauge Widget. This helps employees track their current status and motivates improvement, while ensuring that no one sees anyone else’s score.

Data Setup

You have a Zenphi Table named "Employee Performance" with the following columns:

• Full Name (single line text)
• Email (single line text)
• Performance Score (decimal number between 0–100)

Each row represents one employee's performance data.

Gauge Widget Configuration

🔹 Data Source

• Select "Employee Performance" table.

🔹 Gauge Data

• Widget Data Field: Performance Score
• Function: Average (or Maximum if multiple scores exist per person)

🔹 Range

• Min: 0
• Max: 100

🔹 Axisline Colors

• Green up to 70%
• Yellow up to 90%
• Red up to 100%

Example:

Green - 70
Yellow - 90
Red - 100

Appearance Settings

• Prefix: "Your Score: "
• Suffix: "%"
• Widget Title: "Performance Overview"
• Border: Show or Hide based on your dashboard design
• Font size and color: Customize to match your branding

Filter Conditions

To ensure each employee only sees their own score:

• Condition:Email → equal to → {{user.email}} (selected via token picker)

This ensures that when a user views the dashboard, the widget pulls data only from the row where the email matches their logged-in identity.

✅ Result

When Alex ([email protected]) opens the dashboard:

• The Gauge Widget shows only Alex’s performance score.

• The color reflects how well Alex is performing:

  • Green: Good
  • Yellow: Needs attention
  • Red: Critical

Meanwhile, when Jamie ([email protected]) logs in, they see their own score instead—with no access to others' data.

💡 Bonus Tip

Use this setup with Zenphi Forms to allow managers to update performance scores directly into the table. As data updates, the gauge will reflect the new value instantly.