Getting Started
UI
Components
- Accordion
- Alert
- Alert Dialog
- Aspect Ratio
- Autocomplete
- Avatar
- Badge
- Breadcrumb
- Button
- Button Group
- Calendar
- Card
- Carousel
- Checkbox
- Collapsible
- Combobox
- Command
- Context Menu
- Data Table
- Date Picker
- Dialog
- Dropdown Menu
- Empty
- Field
- Hover Card
- Icon
- Input Group
- Input OTP
- Input
- Item
- Kbd
- Label
- Menubar
- Native Select
- Navigation Menu
- Pagination
- Popover
- Progress
- Radio Group
- Resizable
- Scroll Area
- Select
- Separator
- Sheet
- Sidebar
- Skeleton
- Slider
- Sonner (Toast)
- Spinner
- Switch
- Table
- Tabs
- Textarea
- Toggle
- Toggle Group
- Tooltip
Forms
Stack
Spinner
Shows a Loading spinner to indicate that the app is busy or the page is still loading.
Processing payment...
import { Component } from '@angular/core';
import { HlmItemImports } from '@spartan-ng/helm/item';
import { HlmSpinnerImports } from '@spartan-ng/helm/spinner';
@Component({
selector: 'spartan-spinner-preview',
imports: [HlmSpinnerImports, HlmItemImports],
template: `
<div className="flex w-full max-w-xs flex-col gap-4 [--radius:1rem]">
<div hlmItem variant="muted">
<hlm-item-media>
<hlm-spinner />
</hlm-item-media>
<hlm-item-content>
<div hlmItemTitle class="line-clamp-1">Processing payment...</div>
</hlm-item-content>
<hlm-item-content>
<span class="text-sm tabular-nums">$100.00</span>
</hlm-item-content>
</div>
</div>
`,
})
export class SpinnerPreview {}About
Spinner is built on top of ng-icons by @ashley-hunter .
Installation
ng g @spartan-ng/cli:ui spinnernx g @spartan-ng/cli:ui spinnerimport { DestroyRef, ElementRef, HostAttributeToken, Injector, PLATFORM_ID, effect, inject, runInInjectionContext } from '@angular/core';
import { clsx, type ClassValue } from 'clsx';
import { isPlatformBrowser } from '@angular/common';
import { twMerge } from 'tailwind-merge';
export function hlm(...inputs: ClassValue[]) {
return twMerge(clsx(inputs));
}
// Global map to track class managers per element
const elementClassManagers = new WeakMap<HTMLElement, ElementClassManager>();
// Global mutation observer for all elements
let globalObserver: MutationObserver | null = null;
const observedElements = new Set<HTMLElement>();
interface ElementClassManager {
element: HTMLElement;
sources: Map<number, { classes: Set<string>; order: number }>;
baseClasses: Set<string>;
isUpdating: boolean;
nextOrder: number;
hasInitialized: boolean;
restoreRafId: number | null;
/** Transitions are suppressed until the first effect writes correct classes */
transitionsSuppressed: boolean;
/** Original inline transition value to restore after suppression (empty string = none was set) */
previousTransition: string;
/** Original inline transition priority to preserve !important when restoring */
previousTransitionPriority: string;
}
let sourceCounter = 0;
/**
* This function dynamically adds and removes classes for a given element without requiring
* the a class binding (e.g. `[class]="..."`) which may interfere with other class bindings.
*
* 1. This will merge the existing classes on the element with the new classes.
* 2. It will also remove any classes that were previously added by this function but are no longer present in the new classes.
* 3. Multiple calls to this function on the same element will be merged efficiently.
*/
export function classes(computed: () => ClassValue[] | string, options: ClassesOptions = {}) {
runInInjectionContext(options.injector ?? inject(Injector), () => {
const elementRef = options.elementRef ?? inject(ElementRef);
const platformId = inject(PLATFORM_ID);
const destroyRef = inject(DestroyRef);
const baseClasses = inject(new HostAttributeToken('class'), { optional: true });
const element = elementRef.nativeElement;
// Create unique identifier for this source
const sourceId = sourceCounter++;
// Get or create the class manager for this element
let manager = elementClassManagers.get(element);
if (!manager) {
// Initialize base classes from variation (host attribute 'class')
const initialBaseClasses = new Set<string>();
if (baseClasses) {
toClassList(baseClasses).forEach((cls) => initialBaseClasses.add(cls));
}
manager = {
element,
sources: new Map(),
baseClasses: initialBaseClasses,
isUpdating: false,
nextOrder: 0,
hasInitialized: false,
restoreRafId: null,
transitionsSuppressed: false,
previousTransition: '',
previousTransitionPriority: '',
};
elementClassManagers.set(element, manager);
// Setup global observer if needed and register this element
setupGlobalObserver(platformId);
observedElements.add(element);
// Suppress transitions until the first effect writes correct classes and
// the browser has painted them. This prevents CSS transition animations
// during hydration when classes change from SSR state to client state.
if (isPlatformBrowser(platformId)) {
manager.previousTransition = element.style.getPropertyValue('transition');
manager.previousTransitionPriority = element.style.getPropertyPriority('transition');
element.style.setProperty('transition', 'none', 'important');
manager.transitionsSuppressed = true;
}
}
// Assign order once at registration time
const sourceOrder = manager.nextOrder++;
function updateClasses(): void {
// Get the new classes from the computed function
const newClasses = toClassList(computed());
// Update this source's classes, keeping the original order
manager!.sources.set(sourceId, {
classes: new Set(newClasses),
order: sourceOrder,
});
// Update the element
updateElement(manager!);
// Re-enable transitions after the first effect writes correct classes.
// Deferred to next animation frame so the browser paints the class change
// with transitions disabled first, then re-enables them.
if (manager!.transitionsSuppressed) {
manager!.transitionsSuppressed = false;
manager!.restoreRafId = requestAnimationFrame(() => {
manager!.restoreRafId = null;
restoreTransitionSuppression(manager!);
});
}
}
// Register cleanup with DestroyRef
destroyRef.onDestroy(() => {
if (manager!.restoreRafId !== null) {
cancelAnimationFrame(manager!.restoreRafId);
manager!.restoreRafId = null;
}
if (manager!.transitionsSuppressed) {
manager!.transitionsSuppressed = false;
restoreTransitionSuppression(manager!);
}
// Remove this source from the manager
manager!.sources.delete(sourceId);
// If no more sources, clean up the manager
if (manager!.sources.size === 0) {
cleanupManager(element);
} else {
// Update element without this source's classes
updateElement(manager!);
}
});
/**
* We need this effect to track changes to the computed classes. Ideally, we would use
* afterRenderEffect here, but that doesn't run in SSR contexts, so we use a standard
* effect which works in both browser and SSR.
*/
effect(updateClasses);
});
}
function restoreTransitionSuppression(manager: ElementClassManager): void {
const prev = manager.previousTransition;
if (prev) {
manager.element.style.setProperty('transition', prev, manager.previousTransitionPriority || undefined);
} else {
manager.element.style.removeProperty('transition');
}
}
// eslint-disable-next-line @typescript-eslint/no-wrapper-object-types
function setupGlobalObserver(platformId: Object): void {
if (isPlatformBrowser(platformId) && !globalObserver) {
// Create single global observer that watches the entire document
globalObserver = new MutationObserver((mutations) => {
for (const mutation of mutations) {
if (mutation.type === 'attributes' && mutation.attributeName === 'class') {
const element = mutation.target as HTMLElement;
const manager = elementClassManagers.get(element);
// Only process elements we're managing
if (manager && observedElements.has(element)) {
if (manager.isUpdating) continue; // Ignore changes we're making
// Update base classes to include any externally added classes
const currentClasses = toClassList(element.className);
const allSourceClasses = new Set<string>();
// Collect all classes from all sources
for (const source of manager.sources.values()) {
for (const className of source.classes) {
allSourceClasses.add(className);
}
}
// Any classes not from sources become new base classes
manager.baseClasses.clear();
for (const className of currentClasses) {
if (!allSourceClasses.has(className)) {
manager.baseClasses.add(className);
}
}
updateElement(manager);
}
}
}
});
// Start observing the entire document for class attribute changes
globalObserver.observe(document, {
attributes: true,
attributeFilter: ['class'],
subtree: true, // Watch all descendants
});
}
}
function updateElement(manager: ElementClassManager): void {
if (manager.isUpdating) return; // Prevent recursive updates
manager.isUpdating = true;
// Handle initialization: capture base classes after first source registration
if (!manager.hasInitialized && manager.sources.size > 0) {
// Get current classes on element (may include SSR classes)
const currentClasses = toClassList(manager.element.className);
// Get all classes that will be applied by sources
const allSourceClasses = new Set<string>();
for (const source of manager.sources.values()) {
source.classes.forEach((className) => allSourceClasses.add(className));
}
// Only consider classes as "base" if they're not produced by any source
// This prevents SSR-rendered classes from being preserved as base classes
currentClasses.forEach((className) => {
if (!allSourceClasses.has(className)) {
manager.baseClasses.add(className);
}
});
manager.hasInitialized = true;
}
// Get classes from all sources, sorted by registration order (later takes precedence)
const sortedSources = Array.from(manager.sources.entries()).sort(([, a], [, b]) => a.order - b.order);
const allSourceClasses: string[] = [];
for (const [, source] of sortedSources) {
allSourceClasses.push(...source.classes);
}
// Combine base classes with all source classes, ensuring base classes take precedence
const classesToApply =
allSourceClasses.length > 0 || manager.baseClasses.size > 0
? hlm([...allSourceClasses, ...manager.baseClasses])
: '';
// Apply the classes to the element
if (manager.element.className !== classesToApply) {
manager.element.className = classesToApply;
}
manager.isUpdating = false;
}
function cleanupManager(element: HTMLElement): void {
// Remove from global tracking
observedElements.delete(element);
elementClassManagers.delete(element);
// If no more elements being tracked, cleanup global observer
if (observedElements.size === 0 && globalObserver) {
globalObserver.disconnect();
globalObserver = null;
}
}
interface ClassesOptions {
elementRef?: ElementRef<HTMLElement>;
injector?: Injector;
}
// Cache for parsed class lists to avoid repeated string operations
const classListCache = new Map<string, string[]>();
function toClassList(className: string | ClassValue[]): string[] {
// For simple string inputs, use cache to avoid repeated parsing
if (typeof className === 'string' && classListCache.has(className)) {
return classListCache.get(className)!;
}
const result = clsx(className)
.split(' ')
.filter((c) => c.length > 0);
// Cache string results, but limit cache size to prevent memory growth
if (typeof className === 'string' && classListCache.size < 1000) {
classListCache.set(className, result);
}
return result;
}import { ChangeDetectionStrategy, Component, input } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { classes } from '@spartan-ng/helm/utils';
import { lucideLoader2 } from '@ng-icons/lucide';
@Component({
selector: 'hlm-spinner',
imports: [NgIcon],
providers: [provideIcons({ lucideLoader2 })],
changeDetection: ChangeDetectionStrategy.OnPush,
host: {
role: 'status',
'[attr.aria-label]': 'ariaLabel()',
},
template: `
<ng-icon [name]="icon()" />
`,
})
export class HlmSpinner {
/**
* The name of the icon to be used as the spinner.
* Use provideIcons({ ... }) to register custom icons.
*/
public readonly icon = input<string>('lucideLoader2');
/** Aria label for the spinner for accessibility. */
public readonly ariaLabel = input<string>('Loading', { alias: 'aria-label' });
constructor() {
classes(() => 'inline-flex size-fit text-base motion-safe:animate-spin');
}
}
export const HlmSpinnerImports = [HlmSpinner] as const;Usage
import { HlmSpinnerImports } from '@spartan-ng/helm/spinner';<hlm-spinner class="text-base md:text-lg" />Examples
Custom Icon
You can replace the default spinner icon with any other icon by editing the HlmSpinner component.
If you only need to change the icon once, set the icon input to your desired icon icon="lucideLoader" and add provideIcons({ lucideLoader }) to load your custom icon.
import { Component } from '@angular/core';
import { provideIcons } from '@ng-icons/core';
import { lucideLoader } from '@ng-icons/lucide';
import { HlmSpinnerImports } from '@spartan-ng/helm/spinner';
@Component({
selector: 'spartan-spinner-custom-preview',
imports: [HlmSpinnerImports],
providers: [provideIcons({ lucideLoader })],
template: `
<div class="flex items-center">
<hlm-spinner icon="lucideLoader" />
</div>
`,
})
export class SpartanSpinnerCustomPreview {}Size
import { Component } from '@angular/core';
import { HlmSpinnerImports } from '@spartan-ng/helm/spinner';
@Component({
selector: 'spartan-spinner-size-preview',
imports: [HlmSpinnerImports],
template: `
<div class="flex items-center gap-6">
<hlm-spinner class="text-xs" />
<hlm-spinner class="text-base" />
<hlm-spinner class="text-2xl" />
<hlm-spinner class="text-[2rem]" />
</div>
`,
})
export class SpartanSpinnerSizePreview {}Color
import { Component } from '@angular/core';
import { HlmSpinnerImports } from '@spartan-ng/helm/spinner';
@Component({
selector: 'spartan-spinner-color-preview',
imports: [HlmSpinnerImports],
template: `
<div class="flex items-center gap-6">
<hlm-spinner class="text-2xl text-red-500" />
<hlm-spinner class="text-2xl text-green-500" />
<hlm-spinner class="text-2xl text-blue-500" />
<hlm-spinner class="text-2xl text-yellow-500" />
<hlm-spinner class="text-2xl text-purple-500" />
</div>
`,
})
export class SpartanSpinnerColorPreview {}Button
import { Component } from '@angular/core';
import { HlmButtonImports } from '@spartan-ng/helm/button';
import { HlmSpinnerImports } from '@spartan-ng/helm/spinner';
@Component({
selector: 'spartan-spinner-button-preview',
imports: [HlmSpinnerImports, HlmButtonImports],
template: `
<div class="flex flex-col items-center gap-4">
<button hlmBtn size="sm" disabled>
<hlm-spinner />
Loading...
</button>
<button hlmBtn variant="outline" size="sm" disabled>
<hlm-spinner />
Please wait
</button>
<button hlmBtn variant="secondary" size="sm" disabled>
<hlm-spinner />
Processing
</button>
</div>
`,
})
export class SpartanSpinnerButtonPreview {}Badge
import { Component } from '@angular/core';
import { HlmBadgeImports } from '@spartan-ng/helm/badge';
import { HlmSpinnerImports } from '@spartan-ng/helm/spinner';
@Component({
selector: 'spartan-spinner-badge-preview',
imports: [HlmSpinnerImports, HlmBadgeImports],
template: `
<div class="flex items-center gap-4 [--radius:1.2rem]">
<span hlmBadge>
<hlm-spinner class="text-xs" />
Syncing
</span>
<span hlmBadge variant="secondary">
<hlm-spinner class="text-xs" />
Updating
</span>
<span hlmBadge variant="outline">
<hlm-spinner class="text-xs" />
Processing
</span>
</div>
`,
})
export class SpartanSpinnerBadgePreview {}Input Group
Input Group can have spinners inside HlmInputGroupAddon
import { Component } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { lucideArrowUp } from '@ng-icons/lucide';
import { HlmInputGroupImports } from '@spartan-ng/helm/input-group';
import { HlmSpinnerImports } from '@spartan-ng/helm/spinner';
@Component({
selector: 'spartan-spinner-input-group-preview',
imports: [HlmSpinnerImports, HlmInputGroupImports, NgIcon],
providers: [provideIcons({ lucideArrowUp })],
template: `
<div class="flex w-full max-w-md flex-col gap-4">
<hlm-input-group>
<input hlmInputGroupInput placeholder="Send a message..." disabled />
<hlm-input-group-addon align="inline-end">
<hlm-spinner />
</hlm-input-group-addon>
</hlm-input-group>
<hlm-input-group>
<textarea hlmInputGroupTextarea placeholder="Send a message..." disabled></textarea>
<hlm-input-group-addon align="block-end">
<hlm-spinner />
Validating...
<button class="ml-auto" hlmInputGroupButton variant="default">
<ng-icon name="lucideArrowUp" />
<span class="sr-only">Send</span>
</button>
</hlm-input-group-addon>
</hlm-input-group>
</div>
`,
})
export class SpartanSpinnerInputGroupPreview {}Empty
Processing your request
Please wait while we process your request. Do not refresh the page.
import { Component } from '@angular/core';
import { HlmButtonImports } from '@spartan-ng/helm/button';
import { HlmEmptyImports } from '@spartan-ng/helm/empty';
import { HlmSpinnerImports } from '@spartan-ng/helm/spinner';
@Component({
selector: 'spartan-spinner-empty-preview',
imports: [HlmSpinnerImports, HlmEmptyImports, HlmButtonImports],
template: `
<hlm-empty>
<hlm-empty-header>
<hlm-empty-media variant="icon">
<hlm-spinner />
</hlm-empty-media>
<div hlmEmptyTitle>Processing your request</div>
<div hlmEmptyDescription>Please wait while we process your request. Do not refresh the page.</div>
</hlm-empty-header>
<hlm-empty-content>
<button hlmBtn variant="outline" size="sm">Cancel</button>
</hlm-empty-content>
</hlm-empty>
`,
})
export class SpartanSpinnerEmptyPreview {}Item
Use the spinner inside HlmItemMedia to indicate a loading state.
129 MB / 1000 MB
import { Component } from '@angular/core';
import { HlmButtonImports } from '@spartan-ng/helm/button';
import { HlmItemImports } from '@spartan-ng/helm/item';
import { HlmProgressImports } from '@spartan-ng/helm/progress';
import { HlmSpinnerImports } from '@spartan-ng/helm/spinner';
@Component({
selector: 'spartan-spinner-item-preview',
imports: [HlmSpinnerImports, HlmItemImports, HlmButtonImports, HlmProgressImports],
template: `
<div class="flex w-full max-w-md flex-col gap-4 [--radius:1rem]">
<div hlmItem variant="outline">
<hlm-item-media variant="icon">
<hlm-spinner />
</hlm-item-media>
<hlm-item-content>
<hlm-item-title>Downloading...</hlm-item-title>
<p hlmItemDescription>129 MB / 1000 MB</p>
</hlm-item-content>
<hlm-item-actions class="hidden sm:flex">
<button hlmBtn variant="outline" size="sm">Cancel</button>
</hlm-item-actions>
<hlm-item-footer>
<hlm-progress value="75">
<hlm-progress-indicator />
</hlm-progress>
</hlm-item-footer>
</div>
</div>
`,
})
export class SpartanSpinnerItemPreview {}Helm API
HlmSpinner
Selector: hlm-spinner
Inputs
| Prop | Type | Default | Description |
|---|---|---|---|
| icon | string | lucideLoader2 | The name of the icon to be used as the spinner. Use provideIcons({ ... }) to register custom icons. |
| aria-label | string | Loading | Aria label for the spinner for accessibility. |
On This Page
Stop configuring. Start shipping.
Zerops powers spartan.ng and Angular teams worldwide.
One-command deployment. Zero infrastructure headaches.
Deploy with Zerops