# Progress Bar
Progress Bars provide a way to represent the percentage of completion of a range of values starting from zero. In contrast with the rest of the UI components, progress bars are not meant to be interactable by the user, they are display-only components. Therefore, they are not focusable and the navigation won't consider them at all.
The addon offers three convenient ways to represent a value:
1. **By Width**: The object is stretched or clipped along its width to represent the value.
2. **Radial Circle**: The texture is rendered in a radial shape within the bounding box of the object, similar to a pie chart. This rendering mode is exclusively for objects that support meshes, such as [Sprites](https://www.construct.net/en/make-games/manuals/construct-3/plugin-reference/sprite) and [Tiled Backgrounds](https://www.construct.net/en/make-games/manuals/construct-3/plugin-reference/tiled-background).
3. **Radial Square**: The texture is rendered within the bounding box like in the Radial Circle mode, except that the shape of the texture is not modified. Instead, it is rendered radially.
{% hint style="warning" %}
Progress bars rendered ***by width*** are based on its width at the moment it gets initialized by the framework. You can't directly change its width afterwards.
{% endhint %}
{% hint style="info" %}
When placed within a [Container Behavior](/framework-addons/container-behavior.md) they will render based on the width of the parent container. By changing the container's width, you'll be able to set a new widht and render the bar as expected.
{% endhint %}
Progress bars should render from left to right. It means that the origin point must be at the left-most part to render as a typical progress-bar. Ocasionally, you may want the bar to render from a different origin point, which is totally supported. Adjust the origin point according to your needs.
Download
## :tv: Basic Setup - Tutorial Video
{% embed url="" %}
## Properties
| **Property** | **Description** |
| :----------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| `Enabled` | Enables or Disables the Progress Bar. Value can still be set and it will change the progress bar, but animations won't be triggered. You can use the IsEnabled condition to affect the look and feel when needed. |
| `Automatic-Color` | Enables the component to darken a bit when its state is Disabled or when it's focused. Auto-Color is meant to provide a quick identification of the component state. For more specialized customizations, use the component events and disable this check. |
| `Name` | Unique name string for identifying the progress bar |
| `Render Mode` | Define the rendering mode: By Width, Circle Radial (mesh), Square Radial (mesh) |
| `Value` | Numeric value representing the current progress. |
| `Max.Value` | Maximum value representing the 100%. |
| `Animation time` | Time in seconds to complete the animation when changing the value of the progress bar. |
| `Animation Easing` | Easing function to animate the value change. |
| `Arc length` | Maximum arc length in degrees to render radial progress. Enter 360 for a full circle/square. |
| `Mesh Points` | \[Radial Circular Only] Maximum number of mesh points to render the arc for any type of radial progress. Keep this value at the minimum required to maintain optimal performance. Values should be between 2 and 50. |
| `Donut Offset` | \[Radial Circular Only] Creates a 'donut hole' effect when rendering. The values represent the percentage of the texture to be displaced in order to create the hole. |
| `Arc Offset` | A rotation in degrees to offset the orientation and start angle of the rendered arc. Values accepted are from -45 to 45. |
| `Texture Mode` | Defines how the texture will be treated when rendering the progress bar. 'Stretch' will stretch the texture across each triangle of the mesh. 'Clip' will maintain the texture's original properties, clipping it within the rendering mesh. |
## Smart UI Progress Bar ACEs
Smart UI Progress Bar behavior handles progress bar UI components. It provides built-in animations and triggers to handle value changes. The component offers three render methods: by width, radial square, and radial circle. When rendering width, if you use it as part of a hierarcy, you must add it to an object using a [Smart UI Container](/framework-addons/container-behavior.md) behavior to be rendered correctly, since it will use its parent width as the base for rendering.
## Actions
***
### `Set Animation`
Sets the animation function of the progress bar.
| **Parameter** | **Description** |
| :-----------: | :------------------------------------------------------------------------------: |
| `Animation` | Animation easing to be applied every time the value of the progress bar changes. |
### `Set Animation Time`
Sets the time period in seconds to complete the animation of progress bar.
| **Parameter** | **Description** |
| :-----------: | :------------------------------------------: |
| `Time` | Period in seconds to complete the animation. |
### `Set Arc Offset`
A rotation in degrees to offset the orientation and start angle of the rendered arc.
| **Parameter** | **Description** |
| :-----------: | :-----------------------------------------: |
| `Arc Offset` | Values accepted are from -45 to 45 degrees. |
### `Set Donut Offset`
A percentage to displace the center of the texture to create a 'donut hole'.
| **Parameter** | **Description** |
| :-----------: | :--------------------------------------: |
| `Offset` | Percentage value from 0-1. E.g. 0.5=50%. |
### `Set Enabled`
Disable/Enable the Button
| **Parameter** | **Description** |
| :-----------: | :--------------: |
| `Enabled` | Enabled/Disabled |
### `Set Max`
Sets the maximum value of the progress bar.
| **Parameter** | **Description** |
| :-----------: | :----------------------------------: |
| `Value` | Maximum value representing the 100%. |
### `Set Arc Length`
Maximum arc length in degrees to render radial progress. Enter 360 for a full circle/square.
| **Parameter** | **Description** |
| :-----------: | :-------------------: |
| `Arc Length` | Arc lenght in degrees |
### `Set Mesh Points`
\[Radial Circular Only] Maximum number of mesh points to render the arc for any type of radial progress.
| **Parameter** | **Description** |
| :-----------: | :------------------------------: |
| `Points` | Mesh points. Between 2-50 points |
### `Set Name`
Sets the name of the component.
| **Parameter** | **Description** |
| :-----------: | :-------------------: |
| `Name` | Name of the component |
### `Set Render Mode`
Define the rendering mode: By Width, Circle Radial (mesh), Square Radial (mesh).
| **Parameter** | **Description** |
| :-----------: | :----------------------: |
| `Mode` | Progress bar render mode |
### `Set Texture Mode`
Defines how the texture will be treated when rendering the progress bar. 'Stretch' will stretch the texture across each triangle of the mesh. 'Clip' will maintain the texture's original properties, clipping it within the rendering mesh.
| **Parameter** | **Description** |
| :-----------: | :---------------------: |
| `Mode` | Texture rendering mode. |
### `Set Value`
Sets the current value of the progress bar. If the value is below 0 or above the maximum, it will be clamped.
| **Parameter** | **Description** |
| :-----------: | :---------------------------------------------: |
| `Value` | Numeric value representing the current progress |
| `Mode` | Indicate whether or not bypass the animation |
## Conditions
***
### `Compare Value`
Compares the value of the progress bar.
| **Parameter** | **Description** |
| :-----------: | :---------------------------: |
| `Comparison` | How to compare the variable |
| `Value` | Value to compare the variable |
### `Compare Name`
Returns true if the progress bar components name equals the parameter
| **Parameter** | **Description** |
| :-----------: | :----------------------------------------: |
| `Name` | Name to compare with the component picked. |
### `Is Enabled`
Returns true if the Progress Bar is enabled
### `On Animated Value`
Triggered when the progress bar animation is running. Use it to in combination of expressions AnimatedValue and AnimatedProgress to retrieve the animation data.
### `On Animation Finished`
Triggered when the progress bar animation completes.
## Expressions
***
### `AnimatedProgress`
Percentage representing the AnimatedValue from the Max value allowed to be set for the progress bar. This value is set only when the animation is running
### `AnimatedValue`
Current animated value. This value is set only when the animation is running. E.G. If you are changing the value from 0 to 10, it will contain all the step values to reach the 10, as if it was counting.
### `Name`
Component name
### `Max`
Progress Bar Maximum value.
### `Progress`
Progress Bar progress value in percentage.
### `Value`
Progress Bar current value.
**(c) Pixel Perfect Studio 2025**
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://smartui-docs.pixelperfectstudio.mx/framework-addons/progress-bar.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.