feat: add ProgressBar element

[BitRevenant]

Summary

Adds a new ProgressBar element for displaying determinate and indeterminate progress.

The element supports:

• Determinate progress with configurable minimum, maximum, and current values.
• Optional percentage, raw value, or fraction text.
• Indeterminate loading animation.
• Animated value updates.
• Custom value formatting.
• Theme integration.
• Configurable sizing and spacing.

Preview

Usage

Determinate progress

local Progress = Tab:ProgressBar({
    Title = "Download",
    Desc = "Downloading files...",
    Value = {
        Min = 0,
        Max = 100,
        Default = 25,
    },
    ShowValue = true,
})

Progress:Set(75)

Indeterminate progress

local Progress = Tab:ProgressBar({
    Title = "Loading",
    Desc = "Waiting for the operation to finish...",
    Indeterminate = true,
    Speed = 1,
})

Custom value formatting

Tab:ProgressBar({
    Title = "Files",
    Value = {
        Min = 0,
        Max = 20,
        Default = 5,
    },
    Format = function(Value, Percentage, Min, Max)
        return string.format("%d/%d", Value, Max)
    end,
})

Configuration API

Property	Type	Default	Description
Title	string	"Progress"	Element title.
Desc	string?	nil	Optional description.
Value	number | table	0	Current value or { Min, Max, Default }.
Min	number	0	Minimum value when not using the Value table.
Max	number	100	Maximum value when not using the Value table.
Default	number	Min	Initial value when not using the Value table.
Indeterminate	boolean	false	Enables the continuous loading animation.
ShowValue	boolean	not Indeterminate	Shows or hides the value text.
DisplayMode	string	"Percent"	"Percent", "Value", or "Fraction".
Format	function?	nil	Custom value formatter.
Animate	boolean	true	Animates determinate value changes.
AnimationDuration	number	0.15	Duration of value animations.
Speed	number	1	Indeterminate animation speed.
Width	number	160	Width of the progress control.
ValueWidth	number	44	Width reserved for value text.
ControlGap	number	16	Space between the text and progress control.
IndeterminateText	string	""	Text displayed for indeterminate progress when ShowValue is enabled.

Invalid, infinite, and NaN numeric values are ignored. Values are automatically clamped to the configured range, and inverted ranges are normalized.

Methods

Set(Value)

Updates and clamps the current value.

Progress:Set(50)

Get()

Returns the current value.

local Value = Progress:Get()

GetPercentage()

Returns the normalized percentage between 0 and 100.

local Percentage = Progress:GetPercentage()

SetRange(Min, Max)

Updates the complete range and clamps the current value if necessary.

Progress:SetRange(0, 200)

SetMin(Min)

Updates the minimum value.

Progress:SetMin(10)

SetMax(Max)

Updates the maximum value.

Progress:SetMax(150)

Standard WindUI element methods such as SetTitle, SetDesc, Highlight, and Destroy remain available.

Theme keys

The element introduces the following fallback theme keys:

• ProgressBar
• ProgressBarTrack
• ProgressBarTrackTransparency
• ProgressBarText

Existing themes work automatically through the fallback system.

Testing

All public configuration properties and methods documented above were manually tested, including:

• Determinate progress with and without value text.
• Indeterminate animation and custom animation speed.
• Percent, Value, and Fraction display modes.
• Custom value formatting.
• Animated and immediate value updates.
• Custom width, value width, and control spacing.
• Long descriptions and text wrapping.
• Numeric values and { Min, Max, Default } value tables.
• Value clamping, inverted ranges, and invalid numeric input.
• Set, Get, GetPercentage, SetRange, SetMin, and SetMax.
• Theme fallback colors and custom ProgressBar theme keys.

Automated and build verification:

• DarkLua source processing passed.
• DarkLua test processing passed.
• Rojo project build passed.
• The generated bundle was deterministic across consecutive builds.
• git diff --check passed.
• Generated files such as dist/main.lua and sourcemap.json are intentionally excluded from this PR.

[github-actions]

Build Successful

_{Built from commit 54aacf7}

---

Loadstring

loadstring(game:HttpGet("https://raw.githubusercontent.com/Footagesus/WindUI/54aacf78794853c2d00caaac614a2b6836ddcc7a/dist/main.lua"))()

Updated Example

--[[
    WindUI Example 

    example moved to main.client.lua
]]


loadstring(game:HttpGet('https://raw.githubusercontent.com/Footagesus/WindUI/refs/heads/main/main.client.lua'))()