# `PhiaUi.Components.LoadingOverlay`
[🔗](https://github.com/charlenopires/PhiaUI/blob/v0.1.17/lib/phia_ui/components/feedback/loading_overlay.ex#L1)

Loading state components for blocking operations, animated loaders, and
top-of-page progress indicators.

Inspired by Mantine LoadingOverlay, Ant Design Spin, and the NProgress
top-bar pattern used by GitHub, YouTube, and other major SaaS products.

Pure CSS — no JavaScript hooks required.

## Sub-components

| Component          | Purpose                                                      |
|--------------------|--------------------------------------------------------------|
| `loading_overlay/1`| Semi-transparent overlay blocking container/page interactions|
| `loading_dots/1`   | Three-dot bounce animation (alternative to spinner)          |
| `loading_bar/1`    | Slim animated top-of-page progress bar (NProgress style)     |

## Loading overlay (scoped to a container)

    <div class="relative">
      <.loading_overlay visible={@loading} label="Saving changes..." />
      <.form ...>...</.form>
    </div>

## Loading overlay (full screen)

    <.loading_overlay visible={@initializing} fullscreen label="Initializing..." />

## Bouncing dots

    <div class="flex items-center gap-2">
      <.loading_dots />
      <span class="text-sm text-muted-foreground">Processing...</span>
    </div>

## Top progress bar (root layout)

    <%!-- In root.html.heex, shown while navigating --%>
    <.loading_bar :if={@loading} />

# `loading_bar`

Renders a slim indeterminate progress bar at the top of the page.

Inspired by the NProgress library used by GitHub, YouTube, and other apps.
Place at the very top of the viewport (before the main layout) and toggle
visibility via a LiveView assign during navigation or long operations.

The bar runs a shimmer animation indefinitely until removed from the DOM.

## Example

    <%!-- In root.html.heex --%>
    <.loading_bar :if={@page_loading} />
    <header>...</header>
    <main>...</main>

## Attributes

* `class` (`:string`) - Additional CSS classes for the bar. Defaults to `nil`.
* Global attributes are accepted. HTML attrs forwarded to the root `<div>`.

# `loading_dots`

Renders three animated bouncing dots as a loading indicator.

Use as an alternative to `Spinner` when a more playful or compact loader
is appropriate — typing indicators, inline "thinking" states, chat messages.

Each dot staggers its bounce animation for a fluid wave effect.

## Example

    <%!-- Inline beside text --%>
    <div class="flex items-center gap-2 text-muted-foreground">
      <.loading_dots size={:sm} />
      <span class="text-sm">AI is thinking...</span>
    </div>

## Attributes

* `size` (`:atom`) - Size of the dots. Defaults to `:default`. Must be one of `:sm`, `:default`, or `:lg`.
* `label` (`:string`) - Screen-reader-only label. Defaults to `"Loading"`.
* `class` (`:string`) - Additional CSS classes. Defaults to `nil`.
* Global attributes are accepted. HTML attrs forwarded to the wrapper `<span>`.

# `loading_overlay`

Renders a semi-transparent overlay that blocks user interaction during loading.

For scoped containers (a card, a form section), place this as the first child
inside a `position: relative` parent. For full-page blocking, set `fullscreen={true}`.

## Example

    <%!-- Scoped to a card --%>
    <div class="relative rounded-lg border p-6">
      <.loading_overlay visible={@saving} label="Saving..." show_label />
      <.card_content>...</.card_content>
    </div>

    <%!-- Full-page during initial data load --%>
    <.loading_overlay visible={@loading} fullscreen />

## Attributes

* `visible` (`:boolean`) - When `false`, the overlay is not rendered. Defaults to `true`.
* `label` (`:string`) - Accessible label — announced by screen readers and shown below the spinner when `show_label` is true. Defaults to `"Loading..."`.
* `show_label` (`:boolean`) - When `true`, displays the label text below the spinner. Defaults to `false`.
* `fullscreen` (`:boolean`) - When `true`, uses `fixed inset-0` to cover the entire viewport. When `false` (default), uses `absolute inset-0` to cover the nearest `position: relative` ancestor. Defaults to `false`.
* `blur` (`:boolean`) - When `true`, applies a subtle backdrop blur to the underlying content. Defaults to `false`.
* `class` (`:string`) - Additional CSS classes for the overlay. Defaults to `nil`.
* Global attributes are accepted. HTML attrs forwarded to the overlay `<div>`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*