Spinner component is a web component that displays a spinner on top of the content. It can be used for loading states or any other type of information that needs to be displayed on top of the content.
Spinner has different variants to match the design system colors.
Spinner has different sizes to match the design system spacing. You can use the size attribute to set the size of the spinner. The staticSize attribute can be used to set a custom size.
You can add a text to the spinner.
The spinner supports both vertical (default) and horizontal orientations. Use the orientation attribute to change the layout.
The spinner component includes several accessibility features to ensure it works well with screen readers.
Use the aria-label attribute to provide custom screen reader text. If not provided, the component uses localized default text ("Loading..." in English, "Betöltés" in Hungarian).
The aria-live attribute controls how screen readers announce loading states. The default value is "polite" which waits for a pause before announcing. Use "assertive" for critical loading states.
Use the delay attribute to prevent spinner flash on quick loading operations. The spinner will only appear if the loading takes longer than the specified delay (in milliseconds). This improves user experience by avoiding distracting flashes for operations that complete quickly.
A common pattern is to use a 300ms delay for most loading operations. This prevents the spinner from showing for very quick operations while still providing feedback for longer ones.
The spinner automatically respects the user's prefers-reduced-motion system preference. When reduced motion is enabled, the spinning animation is replaced with a fade/pulse effect to avoid motion sickness or distraction.
This accessibility feature is automatic and requires no additional configuration.
Here are examples combining multiple features for common use cases:
import { DapDSSpinner } from 'dap-design-system'
import { DapDSSpinnerReact } from 'dap-design-system/react'
For optimal bundle sizes, use the tree-shakeable import syntax:
import { DapDSSpinner } from 'dap-design-system/components'
| Property | Type | Default | Description |
|---|---|---|---|
variant | "neutral", "brand" , "negative" , "positive" , "inverted" | 'neutral' | The variant of the spinner. |
size | "xxl", "xl" , "lg" , "md" , "sm" , "xs" | 'lg' | The size of the spinner. |
staticSize | number, undefined | The size of the spinner in pixels. This overrides the size attribute | |
text | string | The loading text. | |
noColor | boolean | false | Removes the text color |
orientation | "vertical", "horizontal" | 'vertical' | The orientation of the spinner (icon and text layout). |
ariaLive | "polite", "assertive" , "off" | 'polite' | The aria-live politeness level for screen readers. |
delay | number | 0 | Delay in milliseconds before showing the spinner. |
| Prevents flash for quick operations. |
| Name | Description |
|---|---|
(default) | The loading text content. |
No custom events available.
| Part Name | Description |
|---|---|
base | The main spinner container. |
icon | The loading icon element. |
icon-base | The base of the loading icon. |
text | The loading text element. |
You can style CSS parts using the ::part() pseudo-element selector:
/* Target a specific part */
.my-custom-dap-ds-spinner::part(base) {
/* Your custom styles */
}
/* Target multiple parts */
.my-custom-dap-ds-spinner::part(base),
.my-custom-dap-ds-spinner::part(icon) {
/* Shared styles */
}
Example usage:
<dap-ds-spinner class="my-custom-dap-ds-spinner">
Spinner
</dap-ds-spinner>
.my-custom-dap-ds-spinner::part(base) {
border-radius: 12px;
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}
CSS parts allow you to style internal elements of the component while maintaining encapsulation. Learn more in our styling guide.
| Property Name | Description |
|---|---|
--dds-spinner-icon-color-neutral | Color for neutral spinner icons. |
--dds-spinner-icon-color-brand | Color for brand spinner icons. |
--dds-spinner-icon-color-negative | Color for negative spinner icons. |
--dds-spinner-icon-color-positive | Color for positive spinner icons. |
--dds-spinner-icon-color-inverted | Color for inverted spinner icons. |
--dds-spinner-text-spacing | Spacing between spinner and text. |
--dds-spinner-animation-duration | Duration of the spinner animation. |
CSS custom properties (CSS variables) can be set directly on the component or in your stylesheet:
Method 1: Inline styles (Quick customization)
<dap-ds-spinner
style="--dds-spinner-icon-color-neutral: value; --dds-spinner-icon-color-brand: value;">
Spinner
</dap-ds-spinner>
Method 2: CSS classes (Reusable styles)
.my-custom-dap-ds-spinner {
--dds-spinner-icon-color-neutral: value;
--dds-spinner-icon-color-brand: value;
--dds-spinner-icon-color-negative: value;
}
<dap-ds-spinner class="my-custom-dap-ds-spinner">
Spinner
</dap-ds-spinner>
Method 3: Global theme customization
/* Apply to all instances */
dap-ds-spinner {
--dds-spinner-icon-color-neutral: value;
--dds-spinner-icon-color-brand: value;
}
CSS custom properties inherit through the Shadow DOM, making them perfect for theming. Changes apply immediately without rebuilding.
