> ## Documentation Index
> Fetch the complete documentation index at: https://gabibou-ui.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Loading screens

> Show real startup progress and customize the loader layout.

## Choose an integration

* `UI:Create({Loading = true})` shows the default loader while declarative tabs and controls are built.
* `UI:Create({Loading = {...}})` uses loader options for schema-build progress.
* `UI:CreateLoader(options)` creates a standalone loader for application work you control.
* `UI:Launch(spec)` coordinates optional key validation, sequential steps, the loader, and the final window.

The integrated `Create` loader reports controls constructed. Use a standalone loader or `Launch` steps to report data loading or other work. A displayed percentage represents only the progress your code reports.

In rc.16, the loader card and text use a 0.2-second entrance. Its entrance settles before `Update(options)` changes the loader or completion runs; progress updates can occur during the entrance. Reduced motion skips the entrance transition.

## Presets and options

`Variant` accepts `Compact`, `Centered`, or `Minimal`. Compact is the default and uses a 216 px default height. Centered defaults to 300 px; it centers the logo and title and falls back to compact below 260 px of available card height. Minimal uses compact layout without the logo. `Height` may be set explicitly from 160 to 480 px.

Other options include:

| Option | Default | Notes |
| - | - | - |
| `Title` | `Gabibou UI` | Up to 80 characters |
| `Subtitle` | `Preparing your interface` | Up to 240 characters |
| `MarkText` | `G` | Up to 8 characters; used when no logo image is shown |
| `Logo` | none | `Avatar`, image-content string, or `false` to clear |
| `Width` | 420 | 280–560 px |
| `Padding` | 24 | 12–40 px |
| `LogoSize` | 56 | 24–80 px |
| `ShowSubtitle` | `true` | Toggles the subtitle |
| `ShowPercentage` | `true` | Toggles the numeric progress |
| `ShowLogo` | `true` | Toggles the logo area |
| `ShowActivity` | `true` | Toggles the moving activity indicator |
| `ProgressHeight` | 4 | 2–12 px |
| `BackgroundTransparency` | 0.3 | Full-screen dimmer; 0–1, where 0 is opaque and 1 is transparent |
| `CardTransparency` | 0.1 | Loader panel surface only; 0–1, where 0 is opaque and 1 is transparent |
| `MinimumDuration` | 0 | 0–10 seconds |
| `ExitDuration` | 0.18 | 0–2 seconds |

Other options are `Theme`, `Style`, `Position`, `AnchorPoint`, `Parent`, `DisplayOrder`, `ReducedMotion`, `OnComplete(loader)`, and `OnError(loader, title, index)`. The window's parent, theme, style, and reduced-motion setting are inherited by the integrated loader when omitted. `Update` can change either transparency independently.

## Give the loader room to breathe

`Width` and `Height` set the card's outer size, `Padding` sets space inside its edges, and `LogoSize` sets the avatar or image size. Start with a centered card, then adjust those values to fit your title and status text:

```lua theme={null}
local loader = UI:CreateLoader({
    Variant = "Centered",
    Width = 420,
    Height = 300,
    Padding = 24,
    Logo = "Avatar",
    LogoSize = 56,
})

-- Later, use the compact layout without a logo:
loader:Update({Variant = "Minimal", Height = 216})
```

Use a larger card for longer text or a larger logo. Choose `Minimal` when the title and progress status are enough; it uses the compact layout without a logo.

In rc.19, a crowded `Centered` card automatically hides its logo if the logo, padding, and visible title/subtitle would leave less than 12 px before the status area. The text remains centered, and no option or default layout changes.

![Live rc.21 centered loader showing its title, status, and progress bar](https://mintcdn.com/gabibou-ui/I5Uhr5uQ-CiiLlxQ/images/loader.png?fit=max\&auto=format\&n=I5Uhr5uQ-CiiLlxQ\&q=85\&s=ec897d05dc5c1fc7f9ee8cb196125eef)

*A live rc.21 screenshot of a centered loader during progress.*

## Report progress

```lua theme={null}
local loader = UI:CreateLoader({
    Title = "Starting Garden Tools",
    Subtitle = "Loading preferences",
    Variant = "Centered",
    Height = 300,
    Logo = "Avatar",
    BackgroundTransparency = 0.3, -- full-screen dimmer
    CardTransparency = 0.1, -- loader panel
    MinimumDuration = 0.5,
})

loader:SetProgress(0.25, "Reading profile")
-- Perform the work represented by the next progress update.
loader:SetProgress(0.75, "Preparing controls")
loader:Complete("Ready")
```

`SetProgress(ratio, status)` accepts a ratio from 0 to 1 and optional status text. `SetStatus(text)` changes the status independently. `Complete(status)` sets progress to 100%, honors the remaining minimum display time, plays the exit transition, destroys the loader, then calls `OnComplete`. `Destroy()` cancels it without calling `OnComplete`.

`Update(options)` merges a partial table with the current options and validates before applying it. The current height is preserved when only the variant changes. To change a default compact loader to centered, update both values:

```lua theme={null}
loader:Update({Variant = "Centered", Height = 300})
```

`loader:Run(steps)` accepts a nonempty dense array of `{Title, Run}` entries. Each step runs sequentially and may yield. Progress advances after a step returns successfully. A failure stops the sequence, leaves the loader open, sets a generic `LastError`, and calls `OnError(loader, title, index)` when supplied. Call `Run` only once at a time.

## Compose a custom loading screen

`loader:GetParts()` returns `Overlay`, `Card`, `Logo`, `LogoImage`, `LogoText`, `Title`, `Subtitle`, `StatusPanel`, `Status`, `StatusIndicator`, `Percentage`, `Track`, `Fill`, `Activity`, and `Content`. `StatusPanel` is the framed status area; `Content` is a free frame between the heading and status area.

```lua theme={null}
local loader = UI:CreateLoader({Variant = "Centered", Height = 300})
local parts = loader:GetParts()

local message = Instance.new("TextLabel")
message.BackgroundTransparency = 1
message.Size = UDim2.fromScale(1, 1)
message.Text = "Connecting to your service…"
message.TextColor3 = Color3.fromRGB(240, 240, 240)
message.Parent = parts.Content

loader:SetPartLayout("StatusPanel", {
    Position = UDim2.new(0, 24, 1, -72),
    Size = UDim2.new(1, -48, 0, 48),
})

loader:SetPartLayout("Content", {
    Position = UDim2.fromOffset(24, 168),
    Size = UDim2.new(1, -48, 0, 48),
})
```

`SetPartLayout` and `ResetPartLayout` support `Logo`, `Title`, `Subtitle`, `StatusPanel`, `Status`, `StatusIndicator`, `Percentage`, `Track`, and `Content`. `SetPartLayout` accepts finite `UDim2` `Position`/`Size`, `Vector2` `AnchorPoint` from 0 to 1, and boolean `Visible`. Responsive layout reapplies these overrides on resize. Use `loader:Own(resource)` to release custom connections, tweens, or callbacks when the loader closes. There is no opaque custom-renderer callback; create custom content under `Content`.

See the [loading example](https://gabibou-ui.mintlify.site/examples/loading.md) for a complete `Run(steps)` flow.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.