Spin

This documentation is currently being revised and is in beta status. Content may still change.

This component is being retested for accessibility. The full test is still pending and can only be completed after a release.

Synonyms: Loader, Spinner, Loading Indicator, Waiting Animation

Description: The Spin component is a visual loading indicator that informs users that a process is loading or running in the background. It supports multiple animation variants and can be given a semantic label to ensure accessibility.

Example

Default loading indicator with the standard variant:

<KolSpin _label="Loading animation" _show={true} _variant="dot" />

Accessibility

• The component requires a semantic label via _label that describes the loading state (e.g. "Content is loading"). This is read by screen readers and informs users about the status.
• Animations can be problematic for users with vestibular or neurological impairments. Take into account the system setting prefers-reduced-motion and reduce the animation speed accordingly.
• The component should only be displayed when a process is actually running. Use _show to safely hide and show it.
• Make sure that users do not wait indefinitely for something to load. Set timeouts and display appropriate error messages if the process fails.

Links and References

Usage

Best Practices / Recommendations

• Use the Spin component to inform users about ongoing processes and avoid confusion.
• Place loading indicators in consistent locations in the user interface to improve user experience.
• Avoid multiple simultaneous loading indicators, as this can overload the user interface.
• Combine the loading indicator with informative text to tell users what is currently loading (e.g. "Search results are loading…").
• Respect the system setting prefers-reduced-motion by slowing down or disabling animations if the user prefers this.
• Set sensible timeouts and inform users when a process takes unexpectedly long.

Use Cases

• Retrieving new or updated search results
• Logging in to protected areas and authentication
• Downloading and uploading content
• Loading videos or large media files
• Saving form data
• Retrieving data from external APIs
• Processing longer computations

FAQ

Can I use a custom animation? Yes, with the variant _variant="none" you can include your own animation via CSS and display it through the expert slot. This enables full control over the animation design.

How do I respect the "reduce motion" setting (prefers-reduced-motion)? Use CSS media queries to increase the animation duration or disable animations when prefers-reduced-motion is active.

Should the loading indicator always be combined with text? Yes, combine the visual indicator with explanatory text or a label to provide clarity.

Construction / Technical

Playground

<KolSpin _label="Loading animation" _show={true} _variant="dot" />

Features (with Code)

Visibility Control

The _show attribute determines whether the loading indicator is displayed.

<KolSpin _label="Loading animation" _show={true} _variant="dot" />

Animation Variants

The available variants can be selected via _variant: dot, cycle or none (for custom animations).

<KolSpin _label="Loading animation" _show={true} _variant="dot" />

Label and Semantics

The _label attribute defines a semantic label that is read by screen readers.

<KolSpin _label="Loading animation" _show={true} _variant="dot" />

Custom Animations

With _variant="none" you can include your own animation via CSS and display it through the expert slot:

<style>
 /* https://github.com/vineethtrv/css-loader */
 .loader {
  animation: rotation 2s linear infinite;
  border-color: #444;
  border-radius: 50%;
  border-style: solid solid dotted dotted;
  border-width: 3px;
  box-sizing: border-box;
  display: inline-block;
  height: 48px;
  position: relative;
  width: 48px;
 }
 .loader::after {
  animation: rotationBack 1s linear infinite;
  border-color: #ff3d00;
  border-radius: 50%;
  border-style: solid solid dotted;
  border-width: 3px;
  box-sizing: border-box;
  bottom: 0;
  content: '';
  height: 24px;
  left: 0;
  margin: auto;
  position: absolute;
  right: 0;
  top: 0;
  transform-origin: center center;
  width: 24px;
 }

 @keyframes rotation {
  0% {
   transform: rotate(0deg);
  }
  100% {
   transform: rotate(360deg);
  }
 }
 @keyframes rotationBack {
  0% {
   transform: rotate(0deg);
  }
  100% {
   transform: rotate(-360deg);
  }
 }

 /* https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion#toning_down_the_animation_scaling */
 @media (prefers-reduced-motion) {
  .loader {
   animation-duration: 6s;
  }
  .loader::after {
   animation-duration: 3s;
  }
 }
</style>

<kol-spin _show _variant="none">
 <span className="loader" slot="expert"></span>
</kol-spin>

API

Properties

Property	Attribute	Description	Type	Default
_label	_label	Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.).	string | undefined	undefined
_show	_show	Makes the element show up.	boolean | undefined	undefined
_variant	_variant	Defines which variant should be used for presentation.	"cycle" | "dot" | "none" | undefined	undefined

---