Skip to content

CSS Loaders

Faststrap ships additional CSS-only loaders for interfaces that need more personality than the default Bootstrap Spinner.

Use these for loading states, background jobs, AI generation status, and dashboard refreshes. They are dependency-free and theme-aware.

Quick Start

from faststrap import (
    DotsLoader,
    RingLoader,
    WaveLoader,
    PulseLoader,
    PolygonLoader,
    TypewriterLoader,
    ShadowLoader,
    ProgressRing,
)

DotsLoader(variant="info", label="Searching")
RingLoader(size="48px", variant="success")
WaveLoader(variant="warning")
PulseLoader(size="lg", variant="danger")
PolygonLoader(label="Preparing report")
TypewriterLoader("Generating...")
ShadowLoader("Training...")
ProgressRing(72, variant="success")

Components

Component Purpose
DotsLoader Three bouncing dots.
RingLoader Spinning segmented ring.
WaveLoader Vertical wave bars.
PulseLoader Pulsing circle.
PolygonLoader Shape-shifting geometric loader.
TypewriterLoader Text reveal/typewriter loader.
ShadowLoader Text shadow loading effect.
ProgressRing SVG circular progress indicator.

Common Parameters

Parameter Type Default Description
variant str \| None primary Bootstrap variant color.
label str \| None Loading... Accessible label for screen readers.
size str \| sm \| md \| lg component-specific Loader size.

ProgressRing

ProgressRing(
    42,
    max_value=100,
    variant="primary",
    show_text=True,
    label="Profile completion",
)
Parameter Type Default Description
value int \| float required Current value.
max_value int \| float 100 Maximum value.
show_text bool True Show percentage label in the center.

Accessibility

  • Loader components render role="status" and include visually hidden labels.
  • ProgressRing renders role="progressbar" with aria-valuenow, aria-valuemin, and aria-valuemax.
  • Animations respect prefers-reduced-motion.

API Reference

faststrap.components.feedback.loaders.DotsLoader(*, variant=UNSET, label=UNSET, **kwargs)

Render a three-dot loading animation.

Source code in src/faststrap/components/feedback/loaders.py 
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
@register(category="feedback")
@beta
def DotsLoader(
    *,
    variant: str | None = UNSET,
    label: str | None = UNSET,
    **kwargs: Any,
) -> Div:
    """Render a three-dot loading animation."""
    cfg = resolve_defaults("DotsLoader", variant=variant, label=label)
    c_variant = cfg.get("variant") or "primary"
    c_label = cfg.get("label") or "Loading..."

    user_cls = kwargs.pop("cls", "")
    attrs: dict[str, Any] = {
        "cls": merge_classes("faststrap-dots-loader", user_cls),
        "role": "status",
        "aria_label": c_label,
    }
    style = _variant_style(c_variant)
    if style:
        attrs["style"] = style
    attrs.update(convert_attrs(kwargs))

    return Div(Div(), Div(), Div(), Span(c_label, cls="visually-hidden"), **attrs)

faststrap.components.feedback.loaders.RingLoader(*, variant=UNSET, size=UNSET, label=UNSET, **kwargs)

Render a spinning ring loading animation.

Source code in src/faststrap/components/feedback/loaders.py 
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
@register(category="feedback")
@beta
def RingLoader(
    *,
    variant: str | None = UNSET,
    size: str | None = UNSET,
    label: str | None = UNSET,
    **kwargs: Any,
) -> Div:
    """Render a spinning ring loading animation."""
    cfg = resolve_defaults("RingLoader", variant=variant, size=size, label=label)
    c_variant = cfg.get("variant") or "primary"
    c_size = cfg.get("size") or "64px"
    c_label = cfg.get("label") or "Loading..."

    user_cls = kwargs.pop("cls", "")
    user_style = kwargs.pop("style", "")
    styles = [f"width: {c_size}; height: {c_size};"]
    variant_style = _variant_style(c_variant)
    if variant_style:
        styles.append(variant_style)
    if isinstance(user_style, str) and user_style.strip():
        styles.append(user_style.strip())

    attrs: dict[str, Any] = {
        "cls": merge_classes("faststrap-ring-loader", user_cls),
        "style": " ".join(styles),
        "role": "status",
        "aria_label": c_label,
    }
    attrs.update(convert_attrs(kwargs))

    return Div(Div(), Div(), Div(), Div(), Span(c_label, cls="visually-hidden"), **attrs)

faststrap.components.feedback.loaders.WaveLoader(*, variant=UNSET, label=UNSET, **kwargs)

Render a vertical wave loading animation.

Source code in src/faststrap/components/feedback/loaders.py 
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
@register(category="feedback")
@beta
def WaveLoader(
    *,
    variant: str | None = UNSET,
    label: str | None = UNSET,
    **kwargs: Any,
) -> Div:
    """Render a vertical wave loading animation."""
    cfg = resolve_defaults("WaveLoader", variant=variant, label=label)
    c_variant = cfg.get("variant") or "primary"
    c_label = cfg.get("label") or "Loading..."

    user_cls = kwargs.pop("cls", "")
    attrs: dict[str, Any] = {
        "cls": merge_classes("faststrap-wave-loader", user_cls),
        "role": "status",
        "aria_label": c_label,
    }
    style = _variant_style(c_variant)
    if style:
        attrs["style"] = style
    attrs.update(convert_attrs(kwargs))

    bars = [
        Div(cls="faststrap-wave-bar", style=f"animation-delay: {index * 0.1}s;")
        for index in range(5)
    ]
    return Div(*bars, Span(c_label, cls="visually-hidden"), **attrs)

faststrap.components.feedback.loaders.PulseLoader(*, variant=UNSET, size=UNSET, label=UNSET, **kwargs)

Render a pulsing circle loading animation.

Source code in src/faststrap/components/feedback/loaders.py 
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
@register(category="feedback")
@beta
def PulseLoader(
    *,
    variant: str | None = UNSET,
    size: LoaderSize | None = UNSET,
    label: str | None = UNSET,
    **kwargs: Any,
) -> Div:
    """Render a pulsing circle loading animation."""
    cfg = resolve_defaults("PulseLoader", variant=variant, size=size, label=label)
    c_variant = cfg.get("variant") or "primary"
    c_size = cfg.get("size") or "md"
    c_label = cfg.get("label") or "Loading..."

    user_cls = kwargs.pop("cls", "")
    attrs: dict[str, Any] = {
        "cls": merge_classes("faststrap-pulse-loader", f"pulse-{c_size}", user_cls),
        "role": "status",
        "aria_label": c_label,
    }
    style = _variant_style(c_variant)
    if style:
        attrs["style"] = style
    attrs.update(convert_attrs(kwargs))
    return Div(Div(cls="faststrap-pulse-circle"), Span(c_label, cls="visually-hidden"), **attrs)

faststrap.components.feedback.loaders.PolygonLoader(*, label=UNSET, **kwargs)

Render a shape-shifting polygon loading animation.

Source code in src/faststrap/components/feedback/loaders.py 
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
@register(category="feedback")
@beta
def PolygonLoader(*, label: str | None = UNSET, **kwargs: Any) -> Div:
    """Render a shape-shifting polygon loading animation."""
    cfg = resolve_defaults("PolygonLoader", label=label)
    c_label = cfg.get("label") or "Loading..."

    user_cls = kwargs.pop("cls", "")
    attrs: dict[str, Any] = {
        "cls": merge_classes("faststrap-polygon-loader", user_cls),
        "role": "status",
        "aria_label": c_label,
    }
    attrs.update(convert_attrs(kwargs))
    return Div(Span(c_label, cls="visually-hidden"), **attrs)

faststrap.components.feedback.loaders.TypewriterLoader(text='Loading...', **kwargs)

Render a typewriter-style text loading animation.

Source code in src/faststrap/components/feedback/loaders.py 
162
163
164
165
166
167
168
169
170
171
172
173
174
@register(category="feedback")
@beta
def TypewriterLoader(text: str = "Loading...", **kwargs: Any) -> Div:
    """Render a typewriter-style text loading animation."""
    user_cls = kwargs.pop("cls", "")
    attrs: dict[str, Any] = {
        "cls": merge_classes("faststrap-typewriter-loader", user_cls),
        "data_text": text,
        "role": "status",
        "aria_label": text,
    }
    attrs.update(convert_attrs(kwargs))
    return Div(**attrs)

faststrap.components.feedback.loaders.ShadowLoader(text='Loading...', **kwargs)

Render a bouncing shadow text loading animation.

Source code in src/faststrap/components/feedback/loaders.py 
177
178
179
180
181
182
183
184
185
186
187
188
189
@register(category="feedback")
@beta
def ShadowLoader(text: str = "Loading...", **kwargs: Any) -> Div:
    """Render a bouncing shadow text loading animation."""
    user_cls = kwargs.pop("cls", "")
    attrs: dict[str, Any] = {
        "cls": merge_classes("faststrap-shadow-loader", user_cls),
        "data_text": text,
        "role": "status",
        "aria_label": text,
    }
    attrs.update(convert_attrs(kwargs))
    return Div(**attrs)

faststrap.components.feedback.loaders.ProgressRing(value, *, max_value=100, size=UNSET, variant=UNSET, show_text=UNSET, label=UNSET, **kwargs)

Render a circular SVG progress indicator.

Source code in src/faststrap/components/feedback/loaders.py 
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
@register(category="feedback")
@beta
def ProgressRing(
    value: int | float,
    *,
    max_value: int | float = 100,
    size: str | None = UNSET,
    variant: str | None = UNSET,
    show_text: bool | None = UNSET,
    label: str | None = UNSET,
    **kwargs: Any,
) -> Div:
    """Render a circular SVG progress indicator."""
    cfg = resolve_defaults(
        "ProgressRing",
        size=size,
        variant=variant,
        show_text=show_text,
        label=label,
    )
    c_size = cfg.get("size") or "4rem"
    c_variant = cfg.get("variant") or "primary"
    c_show_text = cfg.get("show_text", True)

    safe_max = max(float(max_value), 1.0)
    percentage = min(100.0, max(0.0, (float(value) / safe_max) * 100.0))
    radius = 45
    circumference = 2 * 3.14159 * radius
    stroke_offset = circumference - (percentage / 100.0) * circumference
    accessible_label = cfg.get("label") or f"{int(percentage)}% complete"

    user_cls = kwargs.pop("cls", "")
    attrs: dict[str, Any] = {
        "cls": merge_classes("faststrap-progress-ring", user_cls),
        "role": "progressbar",
        "aria_label": accessible_label,
        "aria_valuemin": "0",
        "aria_valuemax": str(max_value),
        "aria_valuenow": str(value),
    }
    attrs.update(convert_attrs(kwargs))

    svg = Svg(
        ft(
            "circle",
            cx="50",
            cy="50",
            r=str(radius),
            fill="none",
            stroke="var(--bs-border-color)",
            stroke_width="8",
        ),
        ft(
            "circle",
            cx="50",
            cy="50",
            r=str(radius),
            fill="none",
            stroke=f"var(--bs-{c_variant})",
            stroke_width="8",
            stroke_dasharray=str(circumference),
            stroke_dashoffset=str(stroke_offset),
            stroke_linecap="round",
            transform="rotate(-90 50 50)",
            cls="faststrap-progress-ring-value",
        ),
        viewBox="0 0 100 100",
        style=f"width: {c_size}; height: {c_size};",
        aria_hidden="true",
    )

    children: list[Any] = [svg]
    if c_show_text:
        children.append(
            Div(
                f"{int(percentage)}%",
                cls="position-absolute top-50 start-50 translate-middle fw-bold",
                style="font-size: 0.875rem;",
            )
        )

    return Div(*children, **attrs)