# LoadingOverlay

A **built-in** tag for a loading veil — a dimming layer with a centered spinner over
a box of content, for an area that's fetching or processing. The tag wraps the block
body in a positioned box and lays the veil over it, so it renders right here on the
page. Toggle the veil with `visible`, tune it with the `overlay*` props, and style
the spinner with the `loader*` props.

Use it as `{% loadingoverlay %}` in Markdown, or call it from
Python logic (loops, snippets) via `component('aardvark', 'loadingoverlay', …)`.

## Demonstrations

The covered content is the block body; the veil is on by default (`visible=true`):




This content sits under the loading veil while it's `visible`.




<br>

Source: Markdown

```aardvark
{% loadingoverlay %}
This content sits under the loading veil while it's `visible`.
{% endLoadingoverlay %}
```


Source: Python

```python
component(
    'aardvark', 'loadingoverlay',
    children='This content sits under the loading veil while it is visible.',
)
```



### A blurred veil with a custom spinner

`overlayBlur` frosts the content behind the veil; `loaderType`, `loaderColor`, and
`loaderSize` restyle the spinner:




The veil blurs the content behind it, with a grape "bars" spinner.




<br>

Source: Markdown

```aardvark
{% loadingoverlay overlayBlur=2 overlayBackgroundOpacity=0.55 loaderType='bars' loaderColor='grape' loaderSize='lg' %}
The veil blurs the content behind it, with a grape "bars" spinner.
{% endLoadingoverlay %}
```


Source: Python

```python
component(
    'aardvark', 'loadingoverlay',
    overlayBlur=2,
    overlayBackgroundOpacity=0.55,
    loaderType='bars',
    loaderColor='grape',
    loaderSize='lg',
    children='The veil blurs the content behind it, with a grape bars spinner.',
)
```



### Content revealed (veil hidden)

Set `visible=false` to lift the veil and show the content underneath. Combined with
the `overlayRadius` and `zIndex` props, this is how you'd drive the overlay from
loading to ready in a real app:




The veil is hidden, so this content reads normally.




<br>

Source: Markdown

```aardvark
{% loadingoverlay visible=false overlayRadius='md' %}
The veil is hidden, so this content reads normally.
{% endLoadingoverlay %}
```


Source: Python

```python
component(
    'aardvark', 'loadingoverlay',
    visible=False,
    overlayRadius='md',
    children='The veil is hidden, so this content reads normally.',
)
```



## With other components

The body is ordinary Markdown, so the veil can sit over richer content — here a
[card](/components/data-display/card/) being "loaded":






### Account summary

Numbers refresh while the veil is up.






<br>

Source: Markdown

```aardvark
{% loadingoverlay overlayBlur=1 loaderType='dots' %}
{% card shadow='sm' padding='lg' radius='md' withBorder=true %}
### Account summary

Numbers refresh while the veil is up.
{% endCard %}
{% endLoadingoverlay %}
```


Source: Python

```python
body = component('aardvark', 'card', shadow='sm', padding='lg', radius='md', withBorder=True,
                 children='### Account summary\n\nNumbers refresh while the veil is up.')
component('aardvark', 'loadingoverlay', overlayBlur=1, loaderType='dots', children=body)
```



## Attributes

| Attribute | Values | Description |
| --- | --- | --- |
| `visible` | bool, default `true` | Show the veil + spinner. Set `false` to reveal the covered content. |
| `overlayBackgroundOpacity` | float `0`–`1` | Veil opacity. |
| `overlayBlur` | float (px) | Backdrop blur behind the veil. |
| `overlayRadius` | `xs`–`xl` or a number | Veil corner radius. |
| `loaderType` | `oval` (default), `bars`, `dots` | Spinner style. |
| `loaderSize` | `xs`–`xl` or a number | Spinner size. |
| `loaderColor` | any theme color | Spinner color. |
| `zIndex` | integer | Stacking order of the veil. |

## CSS Selectors

Target the rendered element through its island marker, `[data-aardvark-island="LoadingOverlay"]`, or through the Mantine Styles API classes:


```css
/* Every rendered LoadingOverlay carries this island marker */
[data-aardvark-island="LoadingOverlay"] { }

/* Mantine Styles API classes */
.mantine-LoadingOverlay-root { }
.mantine-LoadingOverlay-overlay { }
.mantine-LoadingOverlay-loader { }
```


## Injecting Attributes

`attr={…}` forwards raw HTML attributes — including event handlers — straight onto the rendered element, so you can wire DOM behavior the tag does not expose. The handler can be a full multi-line script, not just one expression — this one logs the value to the console and shows it in an alert:




This content sits under the loading veil while it's `visible`.




<br>

Source: Markdown

```aardvark
{% loadingoverlay attr={'onclick': '''
const value = this.innerText;
console.log('attr demo value:', value);
alert(value);
'''} %}
This content sits under the loading veil while it's `visible`.
{% endLoadingoverlay %}
```


Source: Python

```python
component(
    'aardvark', 'loadingoverlay',
    children='This content sits under the loading veil while it is `visible`.',
    attr={'onclick': '''
const value = this.innerText;
console.log('attr demo value:', value);
alert(value);
'''},
)
```