The Progress Bar element is a fundamental interface element used to visually convey to the user how much of a process, task, or procedure has been completed. It provides instant feedback to the user during loading steps, form completion processes, transaction progress, or step-based tasks. It enables processes to be tracked in an understandable way with both linear and percentage progress indicators.
The Progress Bar element is supported in both web and mobile applications.
1.1. Common Use Cases
Displaying task completion status (e.g., what percentage of a form has been filled out, the completion rate of a task)
Visualizing the loading or processing process (e.g., file uploading, data processing, synchronization processes)
Monitoring the progress of step-by-step processes (e.g., registration flow, multi-step forms, onboarding processes)
Tracking performance and processes (e.g., daily target completion rate, work progress level)
Create summary KPI indicators on dashboards (e.g., percentage of target achievement)
Inform users during time-consuming processes (e.g., report generation, batch processing)
2. Key Features
Display progress status as a percentage. Progress Bar represents how much of a process has been completed with a clear and understandable percentage value.
Ability to work with static or dynamic data. The percentage value can be provided manually or dynamically from SQL, REST API, or Managed DB actions.
Color and style customizations. Visual settings such as background color, fill color, height, and corner rounding can be easily adjusted.
Animated progress support. When the percentage value changes, the bar advances with smooth transitions, enhancing the user experience.
Ability to use multiple Progress Bar elements on the same page. The progress levels of different processes can be compared on the same screen.
Appearance changes based on the completion percentage. For example: Conditional styles can be used (via the Styling Panel), such as changing the color to green when it reaches 100%.
2.1. Element Settings (Properties)
When you select the Progress Bar element, you can configure the progress percentage, color transitions, sizing, and orientation settings in detail via the Properties panel on the right. All settings are explained below:
Progress Settings
Percent: Determines the fill percentage of the Progress Bar. The value must be between 0 and 100. As the percentage increases, the filled portion of the Progress Bar expands.
Color and Style Settings (Gradient Colors)
First Gradient Color: This is the color used at the start (left or top) of the Progress Bar.
Second Gradient Color: Provides a smooth color transition between the first and last colors. It can be used optionally to create a three-color gradient.
Third Gradient Color: This is the color used at the end (right or bottom) of the Progress Bar. Depending on design needs, only two or three colors can be used together.
Size and Position Settings
Size: Determines the width and height values of the Progress Bar. Thin, thick, or full-width progress bar designs can be created with this setting.
Percentage Display Settings
Hide Percentage: Determines whether the progress percentage is shown to the user.
Open: The percentage value is hidden.
Closed: The percentage value is displayed on or next to the Progress Bar.
Percentage Direction: Determines the direction in which the percentage value will progress. Usage examples:
Left → Right
Right → Left
This setting is especially used in reverse animation or RTL (right-to-left) designs.
Progress Direction Setting
Direction: Determines the general progress direction of the Progress Bar.
Supported direction types:
Horizontal: Left–right or right–left progress
Vertical: Down–up or up–down progress
This setting is used in situations requiring a vertical progress bar.
2.2. Actions That Can Be Added to Elements
As the Progress Bar element is a visual progress component, it does not support triggering actions with user interaction. Therefore, when the element is selected, the ADD ACTION button is not displayed, and no trigger specific to the Progress Bar can be added.
Important points regarding the action structure:
Actions cannot be triggered by clicking, hovering, or dragging on the Progress Bar.
Updating the progress percentage is done by assigning an action to an external UI element (Button, Dropdown, Action Trigger, etc.) that triggers the data source associated with the Progress Bar.
The Progress Bar only visually represents a value; it does not initiate any actions on its own.
If progress is to be updated dynamically, this update must be performed through a linked action.
Actions cannot be defined on the Progress Bar; all process management is triggered by external UI elements that update the percentage value.
3. How to Use the Progress Bar Element
In this section, we will discuss the end-to-end use of the Progress Bar element through an example scenario.
Scenario: Displaying the Monthly Target Completion Rate
In a mobile application or management panel, the Progress Bar is used to quickly and visually show the user how much of a specific target has been completed.
In the scenario:
Monthly sales target
Actual sales amount
values are used to calculate the completion percentage, which is then displayed as a visual progress indicator on the Progress Bar.
For example (Monthly Sales Distribution Data):
Monthly Sales Target → 120,000 ₺
Actual Sales → 98,000 ₺
Completion Rate → 81.67%
Step 1 - Creating the Data Source
Creating a table in the DataSources module:
Go to the Datasources module.
Then go to the Tables tab.
Create a new table named “SalesTargets”.
The table structure to be set up is as follows:
Important Field Names:
PeriodLabel: Indicates the period to which the data belongs (in month or year-month format). It specifies which period's target achievement is displayed on the Progress Bar and provides the user with time information.
MonthlyTarget: Indicates the total sales target set for the relevant period. It represents the maximum value of the Progress Bar and is the basic reference for calculating how much of the target has been completed.
CurrentSales: Shows the total sales amount achieved so far within the specified sales target. It is the basic metric that determines the fill rate of the Progress Bar.
Step 2 - Defining the Necessary Actions
To display and add data in the interface:
You need to define three actions.
Add a new action from the Actions > New SQL Action tab in the Datasources module.
Action Adding Sample Data (InsertCategorySalesStats):
Add the following SQL action to test the application with sample data and press the TEST button.
When applying, delete the SalesTargets section, rewrite SalesTargets, and press Enter. This will add the correct schema name before the table name.
Action that Provides and Filters Data (GetSalesTargets):
SELECT
PeriodLabel,
MonthlyTarget,
CurrentSales,
CAST((CurrentSales / MonthlyTarget) * 100 AS DECIMAL(5,2)) AS CompletionRate
FROM SalesTargets
WHERE PeriodLabel = @SelectedPeriod;
When applying, delete the SalesTargets part, rewrite SalesTargets, and press Enter. This will add the correct schema name before the table name.
Action that provides periods (GetSalesTargetsPeriod):
SELECT Id, PeriodLabel FROM SalesTargets;
When applying, delete the SalesTargets part, retype SalesTargets, and press Enter. This will add the correct schema name before the table name.
Step 3 - Adding Initial Action
Open the UI Design module.
Add the Initial Actions > Custom > Managed Db > GetSalesTargetsPeriod action to the page using the ADD ACTION button.
As the second action, add the Initial Actions > Custom > Managed Db > GetSalesTargets action using the ADD ACTION button.
Set the GetSalesTargets > SelectedPeriod parameter field to Default > Empty.
Step 4 - Element Placement and Style Settings
Add the Elements > Display > Label element from the left panel.
Set the Label > Properties > Value to “Monthly Sales Targets”.
Center the Label > Styling > Layout > Align field vertically and horizontally.
Define the size of the Panel element as Panel > Styling > Layout > Width and Height (250,300) px.
Set the background of the Panel element as Panel > Styling > Fill > White Background.
Set the borders of the panel as Panel > Styling > Style > Border > Radius > 40 px.
Drag and drop the Elements > Container > Row element into the panel element.
Add the Elements > Container > VerticalStack element to the Col field within the Row.
Add the Elements > Charts > ProgressBar element to the Vertical Stack.
Define the color gradient by setting ProgressBar > FirstGradientColor > Red (E13C39).
Similarly, define the second color as ProgressBar > SecondGradientColor > Green (72C240).
Add the Elements > Select Input > SelectBox element below the Progress Bar inside the Vertical Stack.
For the text, add the Elements > Container > Row element to the Panel and select Row > Properties > Desktop > 2.
Center both Cols horizontally and vertically by selecting Col > Styling > Layout > Align.
Drag and drop the Elements > Display > Label element into both Cols.
Copy the created Row element using the first option, Duplicate.
The expected result after all steps is as follows.
Step 5 - Configuring Element Settings
Add the percentage information ProgressBar > Properties > Percent > Action Result > GetSalesTargets > First > CompletionRate.
For the initial value, make the following definition in the SelectBox > Properties > Value field.
Similarly, to display the default value, define the PeriodLabel action result in the SelectBox > Properties > Placeholder field as in the previous step.
To list the options, make the following definition in the SelectBox > Properties > Options field.
To retrieve the Select Box selection information, make the following definition: SelectBox > Add Actions > onChange > Custom > Managed DB > GetSalesTargets.
To retrieve the Select Box selection information, make the following definition: SelectBox > onChange > GetSalesTargets > Components > SelectBox > value > PeriodLabel.
In the first Label in the first column, define Label > Properties > Value as ‘Monthly Target’.
In the first Label in the second column, link the following action result to the Label > Properties > Value field.
In the first Label in the second column, define Label > Properties > Value as ‘Current Amount’.
Link the result of the following action to the Label > Properties > Value field in the first Label of the second column.
Preview:
When the application is tested, the sales target and actual sales amount for the selected period are correctly reflected on the Progress Bar. You can select the month to be displayed via the Select Box.
4. Common Properties
Some fields on the Progress Bar element are used in common across all UI elements. Therefore, detailed explanations of the following properties are provided in the relevant general guide pages:
The following recommendations should be considered to make the Progress Bar more effective, readable, and user-friendly:
Choose meaningful and harmonious gradient color transitions. Colors should be harmonious with each other, especially in three-color gradients.
Use the Hide Percentage setting according to the design. Hiding percentages in complex UI designs provides a clean look.
Determine the thickness of the Progress Bar (Size → height) according to the importance of the process. A thicker bar can be preferred for important processes, while a thinner bar can be preferred for background processes.
Do not display only the percentage; add explanatory text if necessary. For example: “Loading... 40%”.
Add microtext to guide the user in slow-moving processes. Example: “Please wait, report is being prepared.”
6. Limitations
The following limitations should be considered when using the Progress Bar element:
Actions cannot be triggered by user interaction. The Progress Bar is only a visualization tool.
Dynamic progress is not possible unless a data source is connected. The Percent value can only be updated manually or by an action.
The Progress Bar is suitable for displaying a single metric; it cannot display multiple progress values.
