Spin

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.

Playground

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

Features

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

---