Investigate UI Fluidity Issues

User Interface (UI) Fluidity is an important key performance indicator (KPI) for Vega apps, ensuring your users have a smooth navigation experience. Vega apps require a UI Fluidity KPI score of 99% or higher for UI interaction use cases, such as scrolling.

Apps with a lower UI Fluidity KPI often exhibit visual stuttering or jitter, which is noticeable during scrolling actions and animations.

This page outlines the process to identify, analyze, and resolve UI Fluidity issues in your Vega apps.

Prerequisites

Make sure you have:

1. A Vega app project open in Visual Studio (VS Code).
2. An app-specific UI automation script that performs a fast-scroll in your app. If you haven't created this script yet, follow the steps in Measure Fluidity and Foreground Memory.

Step 1: Measure UI Fluidity KPI with App KPI Visualizer

Establish a baseline measurement of your Vega app's UI Fluidity by completing the following steps:

1. In VS Code, open the command palette:

   Mac: Shift + Command ⌘ + P

   Linux: Ctrl + Shift + P

2. Enter Kepler: Launch App KPI Visualizer then press Enter.

   

3. In the KPI Visualizer dialog box, select Application UI Fluidity Test, and then press OK.

   

4. In the Record CPU Profiler dialog box, ensure the checkbox is unmarked then press OK.

   

5. In the Custom Test Scenario dialog box, select Yes.

   

6. Select the UI automation script you created as mentioned in the Before you begin section.

The App KPI Visualizer runs your script and measure the UI Fluidity. You should see a UI Fluidity KPI Score as shown in the following image:

The score is your baseline for improvement. Remember, Vega apps should aim for a UI Fluidity KPI score of 99% or higher.

For more details on KPI measurements and how to interpret them, see Measure App KPIs.

Step 2: Identify component rendering

React's re-rendering mechanism is crucial for keeping the UI up-to-date with the latest state changes. However, excessive or unnecessary re-renders can significantly impact your app's performance and UI fluidity.

To identify and resolve re-rendering issues in your app, follow the steps in Investigate Component Re-rendering Issues.

Step 3: Identify overdraw

Overdraw occurs when components are redrawn unnecessarily, impacting scrolling performance. To optimize your app:

1. Detect overdraw components. Follow the instructions in Detect Overdraw.

2. Avoid overdraw in your app. Follow the guidance in Avoid app overdraw.

Step 4: Identify performance-heavy functions with Vega CPU Profiler

The Vega CPU Profiler, integrated with the App KPI Visualizer, helps identify functions that impact your app's UI Fluidity KPI, particularly during scrolling.

To use the CPU Profiler:

1. Repeat Step 1: Measure UI Fluidity KPI with App KPI Visualizer, but select the checkbox for "Record CPU Profiler".

   

2. After you run the CPU Profiler, App KPI Visualizer generates three artifacts:

   • Fluidity graph
   • CPU profile graph
   • Perfetto trace

3. Analyze the artifacts to identify causes of performance issues (jank). Follow the instructions in Identify UI Rendering Issues.

4. Optimize the identified performance-heavy functions to improve UI Fluidity.

Related topics

• App Performance Best Practices
• Measure App KPIs
• Investigate Component Re-rendering Issues
• 💬 Community: How to improve UI Fluidity

---

Last updated: Sep 30, 2025