Using Gauge to Build Visual Meters in HarmonyOS Next

Read the original article：Using Gauge to Build Visual Meters in HarmonyOS Next

Hi, in this article, you’ll learn how to use the Gauge component in HarmonyOS with ArkTS to create smooth, circular progress meters for fitness, battery, and other real-time data use cases.

📘 Introduction

How can we visualize progress clearly and efficiently on compact screens, like smartwatches or dashboards? HarmonyOS provides a solution: the Gauge component.

Whether you’re building a fitness app showing step count, a battery meter, or a goal tracker, the Gauge allows you to display percentage values in an elegant circular arc format. It also supports customization in color, direction, size, and center content.

In this article, you’ll learn:

How Gauge works in HarmonyOS Next
How to configure and style it with ArkTS
Practical use case example
Tips to ensure the best user experience

🧩 What is Gauge?

The Gauge component is part of ArkUI, designed to visualize values using a circular arc. It’s ideal for wearable and dashboard UIs where space is limited but visual clarity matters.

Key Capabilities:

Visually represents percentage-based values
Custom start and end angles
Foreground and background arcs
Gradient color support
Shadow styling for depth
Custom content inside the gauge (text, icons, etc.)

⚙️ Key Properties and Options

📍 Gauge Main Properties

⚙️ GaugeOptions Fields

🧪 Usage Example

Below is a simple example using Gauge to show a 90% value, centered with large text and a gradient arc:

@Entry
@Component
struct Index {
  build() {
    Column() {
      Gauge({ value: 90, min: 1, max: 100 }) {
        Column() {
          Text('90')
            .fontSize(60)
            .fontColor(Color.White)
            .fontWeight(FontWeight.Medium)
            .textAlign(TextAlign.Center)
            .width('100%')
            .height('100%')
            .textAlign(TextAlign.Center)
            .textOverflow({ overflow: TextOverflow.Ellipsis })
            .maxLines(1)
        }
        .width('100%')
        .height('100%')
      }
      .startAngle(225)
      .endAngle(135)
      .colors(new LinearGradient([
        { color: "#e84026", offset: 0 },
        { color: "#f7ce00", offset: 0.6 },
        { color: "#64bb5c", offset: 1 }
      ]))
      .width('96%')
      .height('96%')
      .strokeWidth(18)
      .padding(10)
    }
    .width('100%')
    .height('100%')
  }
}

🧠 Tips and Tricks

1. Use angles wisely
For semi-circular designs, use startAngle: 225 and endAngle: 135.

2. Keep center content minimal
Stick to short numbers or icons for clarity, especially on small screens.

3. Use gradient colors for better UX
Gradient arcs draw attention and convey motion or completion more intuitively.

4. Add shadows for visual depth
Use .trackShadow() to enhance 3D-like appearance.

5. Stay within valid range
value can stay between 0 and 100. Gauge is designed for percentage-based data.

6. Don’t forget performance
Avoid overusing effects like gradients on low-end devices.

7. Adjust stroke width based on context
Thin arcs feel lighter, thick arcs feel bolder. Balance visual weight with content.

📦 Use Case Ideas

The Gauge component fits a wide range of app scenarios:

Fitness Tracker → Show user’s step or calorie goal progress
Learning App → Show course or lesson completion percentage
Battery Monitor → Display current battery level
Goal Tracker → Visualize task completion
Hydration Tracker → Track daily water intake
System Monitor → Show CPU or memory load
Smart Vehicle App → Visualize tire pressure or fuel status

✅ Conclusion

Gauge is one of the most effective UI tools for visualizing progress in HarmonyOS apps. It combines flexibility, clarity, and modern design — making it perfect for circular UIs on smartwatches and dashboards.

With ArkTS and Gauge, you can deliver elegant user feedback that’s both functional and beautiful.

👉 In our next article, we’ll combine Gauge and ArcButton to build a BMI Calculator for HarmonyOS — a great example of how these components work together in real-world apps.

Try adding Gauge to your next project and let your users see their progress — visually.