Command

Fast, composable, command menu for Angular.

import { Component } from '@angular/core';
import { provideIcons } from '@ng-icons/core';
import {
	lucideCalculator,
	lucideCalendar,
	lucideCog,
	lucidePlus,
	lucideSearch,
	lucideSmile,
	lucideUser,
	lucideWallet,
} from '@ng-icons/lucide';
import { HlmCard, HlmCardImports } from '@spartan-ng/helm/card';
import { HlmCommandImports } from '@spartan-ng/helm/command';
import { HlmIconImports } from '@spartan-ng/helm/icon';

@Component({
	selector: 'spartan-command-preview',
	imports: [HlmCommandImports, HlmIconImports, HlmCardImports],
	providers: [
		provideIcons({
			lucideSearch,
			lucideCalendar,
			lucideSmile,
			lucidePlus,
			lucideUser,
			lucideWallet,
			lucideCog,
			lucideCalculator,
		}),
	],
	hostDirectives: [HlmCard],
	host: {
		class: 'w-full py-0',
	},
	template: `
		<div hlmCardContent class="p-0">
			<hlm-command>
				<hlm-command-input placeholder="Type a command or search..." />
				<hlm-command-list>
					<div *hlmCommandEmptyState hlmCommandEmpty>No results found.</div>
					<hlm-command-group>
						<hlm-command-group-label>Suggestions</hlm-command-group-label>
						<button hlm-command-item value="Calendar">
							<ng-icon name="lucideCalendar" />
							Calendar
						</button>
						<button hlm-command-item value="Search Emoji">
							<ng-icon name="lucideSmile" />
							Search Emoji
						</button>
						<button hlm-command-item value="Calculator" disabled>
							<ng-icon name="lucideCalculator" />
							Calculator
						</button>
					</hlm-command-group>

					<hlm-command-separator />

					<hlm-command-group>
						<hlm-command-group-label>Settings</hlm-command-group-label>

						<button hlm-command-item value="Profile">
							<ng-icon name="lucideUser" />
							Profile
							<hlm-command-shortcut>⌘P</hlm-command-shortcut>
						</button>
						<button hlm-command-item value="Billing">
							<ng-icon name="lucideWallet" />
							Billing
							<hlm-command-shortcut>⌘B</hlm-command-shortcut>
						</button>
						<button hlm-command-item value="Settings">
							<ng-icon name="lucideCog" />
							Settings
							<hlm-command-shortcut>⌘S</hlm-command-shortcut>
						</button>
					</hlm-command-group>
				</hlm-command-list>
			</hlm-command>
		</div>
	`,
})
export class CommandPreview {}

Installation

ng g @spartan-ng/cli:ui command

nx g @spartan-ng/cli:ui command

import { 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 { BooleanInput } from '@angular/cdk/coercion';
import { BrnCommand, BrnCommandEmpty, BrnCommandGroup, BrnCommandInput, BrnCommandItem, BrnCommandList, BrnCommandSeparator } from '@spartan-ng/brain/command';
import { BrnDialogState } from '@spartan-ng/brain/dialog';
import { ChangeDetectionStrategy, Component, Directive, booleanAttribute, computed, input, linkedSignal, output } from '@angular/core';
import { ClassValue } from 'clsx';
import { HlmDialogImports } from '@spartan-ng/helm/dialog';
import { HlmInputGroupImports } from '@spartan-ng/helm/input-group';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { classes, hlm } from '@spartan-ng/helm/utils';
import { lucideSearch } from '@ng-icons/lucide';

@Component({
	selector: 'hlm-command-dialog',
	imports: [HlmDialogImports],
	changeDetection: ChangeDetectionStrategy.OnPush,
	template: `
		<hlm-dialog [state]="_state()" (stateChanged)="stateChanged($event)">
			<hlm-dialog-content
				*hlmDialogPortal="let ctx"
				[class]="_computedDialogContentClass()"
				[showCloseButton]="showCloseButton()"
			>
				<hlm-dialog-header class="sr-only">
					<h2 hlmDialogTitle>{{ title() }}</h2>
					<p hlmDialogDescription>{{ description() }}</p>
				</hlm-dialog-header>
				<ng-content />
			</hlm-dialog-content>
		</hlm-dialog>
	`,
})
export class HlmCommandDialog {
	public readonly title = input<string>('Command Palette');
	public readonly description = input<string>('Search for a command to run...');

	public readonly state = input<BrnDialogState>('closed');
	protected readonly _state = linkedSignal(this.state);

	public readonly showCloseButton = input<boolean, BooleanInput>(false, { transform: booleanAttribute });

	public readonly dialogContentClass = input<ClassValue>('');
	protected readonly _computedDialogContentClass = computed(() => hlm('w-96 p-0', this.dialogContentClass()));

	public readonly stateChange = output<BrnDialogState>();

	protected stateChanged(state: BrnDialogState) {
		this.stateChange.emit(state);
		this._state.set(state);
	}
}

@Directive({
	selector: '[hlmCommandEmptyState]',
	hostDirectives: [BrnCommandEmpty],
})
export class HlmCommandEmptyState {}

@Directive({
	selector: '[hlmCommandEmpty]',
	host: {
		'data-slot': 'command-empty',
	},
})
export class HlmCommandEmpty {
	constructor() {
		classes(() => 'py-6 text-center text-sm');
	}
}

@Directive({
	selector: '[hlmCommandGroupLabel],hlm-command-group-label',
	host: {
		'data-slot': 'command-group-label',
		role: 'presentation',
	},
})
export class HlmCommandGroupLabel {
	constructor() {
		classes(() => 'inline-block');
	}
}

@Directive({
	selector: '[hlmCommandGroup],hlm-command-group',
	hostDirectives: [
		{
			directive: BrnCommandGroup,
			inputs: ['id'],
		},
	],
	host: {
		'data-slot': 'command-group',
	},
})
export class HlmCommandGroup {
	constructor() {
		classes(() => 'text-foreground **:data-[slot=command-group-label]:text-muted-foreground overflow-hidden p-1 **:data-[slot=command-group-label]:px-2 **:data-[slot=command-group-label]:py-1.5 **:data-[slot=command-group-label]:text-xs **:data-[slot=command-group-label]:font-medium block data-hidden:hidden');
	}
}

@Component({
	selector: 'hlm-command-input',
	imports: [HlmInputGroupImports, NgIcon, BrnCommandInput],
	providers: [provideIcons({ lucideSearch })],
	changeDetection: ChangeDetectionStrategy.OnPush,
	host: {
		'data-slot': 'command-input-wrapper',
	},
	template: `
		<hlm-input-group class="bg-input/30 border-input/30 h-8! rounded-lg! shadow-none! *:data-[slot=input-group-addon]:pl-2!">
			<input
				brnCommandInput
				data-slot="command-input"
				class="w-full text-sm outline-hidden disabled:cursor-not-allowed disabled:opacity-50"
				[id]="inputId()"
				[placeholder]="placeholder()"
			/>

			<hlm-input-group-addon>
				<ng-icon name="lucideSearch" class="shrink-0 text-[calc(var(--spacing)*4)] opacity-50" />
			</hlm-input-group-addon>
		</hlm-input-group>
	`,
})
export class HlmCommandInput {
	public readonly inputId = input<string | undefined>();
	public readonly placeholder = input<string>('');

	constructor() {
		classes(() => 'p-1 pb-0');
	}
}

@Directive({
	selector: 'button[hlmCommandItem],button[hlm-command-item]',
	hostDirectives: [
		{
			directive: BrnCommandItem,
			inputs: ['value', 'disabled', 'id'],
			outputs: ['selected'],
		},
	],
	host: {
		'data-slot': 'command-item',
	},
})
export class HlmCommandItem {
	constructor() {
		classes(
			() =>
				'data-selected:bg-muted data-selected:text-foreground relative flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden select-none in-data-[slot=dialog-content]:rounded-lg! [&_ng-icon:not([class*=\'text-\'])]:text-[calc(var(--spacing)*4)] group/command-item w-full data-disabled:pointer-events-none data-disabled:opacity-50 data-hidden:hidden [&>ng-icon]:pointer-events-none [&>ng-icon]:shrink-0',
		);
	}
}

@Directive({
	selector: '[hlmCommandList],hlm-command-list',
	hostDirectives: [
		{
			directive: BrnCommandList,
			inputs: ['id'],
		},
	],
	host: {
		'data-slot': 'command-list',
	},
})
export class HlmCommandList {
	constructor() {
		classes(() => 'no-scrollbar max-h-72 scroll-py-1 outline-none overflow-x-hidden overflow-y-auto');
	}
}

@Directive({
	selector: '[hlmCommandSeparator],hlm-command-separator',
	hostDirectives: [BrnCommandSeparator],
	host: {
		'data-slot': 'command-separator',
	},
})
export class HlmCommandSeparator {
	constructor() {
		classes(() => 'bg-border -mx-1 h-px w-auto block data-hidden:hidden');
	}
}

@Directive({
	selector: '[hlmCommandShortcut],hlm-command-shortcut',
	host: {
		'data-slot': 'command-shortcut',
	},
})
export class HlmCommandShortcut {
	constructor() {
		classes(() => 'text-muted-foreground group-data-[selected]/command-item:text-foreground ms-auto text-xs tracking-widest');
	}
}

@Directive({
	selector: '[hlmCommand],hlm-command',
	hostDirectives: [
		{
			directive: BrnCommand,
			inputs: ['id', 'filter', 'search', 'disabled'],
			outputs: ['valueChange', 'searchChange'],
		},
	],
	host: {
		'data-slot': 'command',
	},
})
export class HlmCommand {
	constructor() {
		classes(() => 'bg-popover text-popover-foreground rounded-xl p-1 flex size-full flex-col overflow-hidden');
	}
}

export const HlmCommandImports = [
	HlmCommand,
	HlmCommandDialog,
	HlmCommandEmpty,
	HlmCommandEmptyState,
	HlmCommandGroup,
	HlmCommandGroupLabel,
	HlmCommandInput,
	HlmCommandItem,
	HlmCommandList,
	HlmCommandSeparator,
	HlmCommandShortcut,
] as const;

Usage

import { HlmCommandImports } from '@spartan-ng/helm/command';

<hlm-command>
  <hlm-command-input placeholder="Type a command or search..." />
  <hlm-command-list>
  	<div *hlmCommandEmptyState hlmCommandEmpty>No results found.</div>
    <hlm-command-group>
      <hlm-command-group-label>Suggestions</hlm-command-group-label>
      <button hlm-command-item value="Calendar">
        <ng-icon name="lucideCalendar" />
        Calendar
      </button>
    </hlm-command-group>
    <hlm-command-separator />
    <hlm-command-group>
      <hlm-command-group-label>Settings</hlm-command-group-label>
      <button hlm-command-item value="Profile">
        <ng-icon name="lucideUser" />
        Profile
        <hlm-command-shortcut>⌘P</hlm-command-shortcut>
      </button>
    </hlm-command-group>
  </hlm-command-list>
</hlm-command>

Examples

Basic

import { Component, signal } from '@angular/core';
import { provideIcons } from '@ng-icons/core';
import {
	lucideCalendar,
	lucideCog,
	lucideLayers,
	lucidePlus,
	lucideSearch,
	lucideSmile,
	lucideUser,
	lucideX,
} from '@ng-icons/lucide';
import { HlmButtonImports } from '@spartan-ng/helm/button';
import { HlmCommandImports } from '@spartan-ng/helm/command';

@Component({
	selector: 'spartan-command-basic',
	imports: [HlmCommandImports, HlmButtonImports],
	providers: [
		provideIcons({
			lucideX,
			lucideCalendar,
			lucideSmile,
			lucidePlus,
			lucideUser,
			lucideLayers,
			lucideCog,
			lucideSearch,
		}),
	],

	template: `
		<div class="mx-auto flex max-w-screen-sm items-center justify-center space-x-4 py-20 text-sm">
			<button hlmBtn variant="outline" (click)="stateChanged('open')">Open Menu</button>
		</div>
		<hlm-command-dialog [state]="state()" (stateChange)="stateChanged($event)">
			<hlm-command>
				<hlm-command-input placeholder="Type a command or search..." />
				<hlm-command-list>
					<div *hlmCommandEmptyState hlmCommandEmpty>No results found.</div>
					<hlm-command-group>
						<hlm-command-group-label>Suggestions</hlm-command-group-label>
						<button hlm-command-item value="calendar" (selected)="commandSelected('calendar')">Calendar</button>
						<button hlm-command-item value="emoji" (selected)="commandSelected('emoji')">Search Emoji</button>
						<button hlm-command-item value="calculator" (selected)="commandSelected('calculator')">Calculator</button>
					</hlm-command-group>
				</hlm-command-list>
			</hlm-command>
		</hlm-command-dialog>
	`,
})
export class CommandBasic {
	public readonly command = signal('');
	public readonly state = signal<'closed' | 'open'>('closed');

	stateChanged(state: 'open' | 'closed') {
		this.state.set(state);
	}

	commandSelected(selected: string) {
		this.state.set('closed');
		this.command.set(selected);
	}
}

Shortcuts

import { Component, signal } from '@angular/core';
import { provideIcons } from '@ng-icons/core';
import {
	lucideCalendar,
	lucideCog,
	lucideLayers,
	lucidePlus,
	lucideSearch,
	lucideSmile,
	lucideUser,
	lucideX,
} from '@ng-icons/lucide';
import { HlmButton } from '@spartan-ng/helm/button';
import { HlmCommandImports } from '@spartan-ng/helm/command';
import { HlmIconImports } from '@spartan-ng/helm/icon';

@Component({
	selector: 'spartan-command-shortcuts',
	imports: [HlmCommandImports, HlmIconImports, HlmButton],
	providers: [
		provideIcons({
			lucideX,
			lucideCalendar,
			lucideSmile,
			lucidePlus,
			lucideUser,
			lucideLayers,
			lucideCog,
			lucideSearch,
		}),
	],
	template: `
		<div class="mx-auto flex max-w-screen-sm items-center justify-center space-x-4 py-20 text-sm">
			<button hlmBtn variant="outline" (click)="stateChanged('open')">Open Menu</button>
		</div>
		<hlm-command-dialog [state]="state()" (stateChange)="stateChanged($event)">
			<hlm-command>
				<hlm-command-input placeholder="Type a command or search..." />
				<hlm-command-list>
					<div *hlmCommandEmptyState hlmCommandEmpty>No results found.</div>
					<hlm-command-group>
						<hlm-command-group-label>Settings</hlm-command-group-label>
						<button hlm-command-item value="profile" (selected)="commandSelected('profile')">
							<ng-icon name="lucideUser" />
							Profile
							<hlm-command-shortcut>⌘P</hlm-command-shortcut>
						</button>
						<button hlm-command-item value="billing" (selected)="commandSelected('billing')">
							<ng-icon name="lucideLayers" />
							Billing
							<hlm-command-shortcut>⌘B</hlm-command-shortcut>
						</button>
						<button hlm-command-item value="settings" (selected)="commandSelected('settings')">
							<ng-icon name="lucideCog" />
							Settings
							<hlm-command-shortcut>⌘S</hlm-command-shortcut>
						</button>
					</hlm-command-group>
				</hlm-command-list>
			</hlm-command>
		</hlm-command-dialog>
	`,
})
export class CommandShortcuts {
	public readonly command = signal('');
	public readonly state = signal<'closed' | 'open'>('closed');

	stateChanged(state: 'open' | 'closed') {
		this.state.set(state);
	}

	commandSelected(selected: string) {
		this.state.set('closed');
		this.command.set(selected);
	}
}

Groups

import { Component, signal } from '@angular/core';
import { provideIcons } from '@ng-icons/core';
import {
	lucideCalendar,
	lucideCog,
	lucideLayers,
	lucidePlus,
	lucideSearch,
	lucideSmile,
	lucideUser,
	lucideX,
} from '@ng-icons/lucide';
import { HlmButton } from '@spartan-ng/helm/button';
import { HlmCommandImports } from '@spartan-ng/helm/command';
import { HlmIconImports } from '@spartan-ng/helm/icon';

@Component({
	selector: 'spartan-command-groups',
	imports: [HlmCommandImports, HlmIconImports, HlmButton],
	providers: [
		provideIcons({
			lucideX,
			lucideCalendar,
			lucideSmile,
			lucidePlus,
			lucideUser,
			lucideLayers,
			lucideCog,
			lucideSearch,
		}),
	],

	template: `
		<div class="mx-auto flex max-w-screen-sm items-center justify-center space-x-4 py-20 text-sm">
			<button hlmBtn variant="outline" (click)="stateChanged('open')">Open Menu</button>
		</div>
		<hlm-command-dialog [state]="state()" (stateChange)="stateChanged($event)">
			<hlm-command>
				<hlm-command-input placeholder="Type a command or search..." />
				<hlm-command-list>
					<div *hlmCommandEmptyState hlmCommandEmpty>No results found.</div>
					<hlm-command-group>
						<hlm-command-group-label>Suggestions</hlm-command-group-label>
						<button hlm-command-item value="calendar" (selected)="commandSelected('calendar')">
							<ng-icon name="lucideCalendar" />
							Calendar
						</button>
						<button hlm-command-item value="emojy" (selected)="commandSelected('emojy')">
							<ng-icon name="lucideSmile" />
							Search Emoji
						</button>
						<button hlm-command-item value="calculator" (selected)="commandSelected('calculator')">
							<ng-icon name="lucidePlus" />
							Calculator
						</button>
					</hlm-command-group>
					<hlm-command-separator />
					<hlm-command-group>
						<hlm-command-group-label>Settings</hlm-command-group-label>
						<button hlm-command-item value="profile" (selected)="commandSelected('profile')">
							<ng-icon name="lucideUser" />
							Profile
							<hlm-command-shortcut>⌘P</hlm-command-shortcut>
						</button>
						<button hlm-command-item value="billing" (selected)="commandSelected('billing')">
							<ng-icon name="lucideLayers" />
							Billing
							<hlm-command-shortcut>⌘B</hlm-command-shortcut>
						</button>
						<button hlm-command-item value="settings" (selected)="commandSelected('settings')">
							<ng-icon name="lucideCog" />
							Settings
							<hlm-command-shortcut>⌘S</hlm-command-shortcut>
						</button>
					</hlm-command-group>
				</hlm-command-list>
			</hlm-command>
		</hlm-command-dialog>
	`,
})
export class CommandGroups {
	public readonly command = signal('');
	public readonly state = signal<'closed' | 'open'>('closed');

	stateChanged(state: 'open' | 'closed') {
		this.state.set(state);
	}

	commandSelected(selected: string) {
		this.state.set('closed');
		this.command.set(selected);
	}
}

Scrollable

import { Component, signal } from '@angular/core';
import { provideIcons } from '@ng-icons/core';
import {
	lucideBell,
	lucideCalculator,
	lucideCalendar,
	lucideCircleHelp,
	lucideClipboardPaste,
	lucideCode,
	lucideCog,
	lucideCopy,
	lucideCreditCard,
	lucideFileText,
	lucideFolder,
	lucideFolderPlus,
	lucideHouse,
	lucideImage,
	lucideInbox,
	lucideLayoutGrid,
	lucideList,
	lucidePlus,
	lucideScissors,
	lucideTrash2,
	lucideUser,
	lucideZoomIn,
	lucideZoomOut,
} from '@ng-icons/lucide';
import { HlmButton } from '@spartan-ng/helm/button';
import { HlmCommandImports } from '@spartan-ng/helm/command';
import { HlmIconImports } from '@spartan-ng/helm/icon';

@Component({
	selector: 'spartan-command-scrollable',
	imports: [HlmCommandImports, HlmIconImports, HlmButton],
	providers: [
		provideIcons({
			lucideHouse,
			lucideInbox,
			lucideFileText,
			lucideFolder,
			lucidePlus,
			lucideFolderPlus,
			lucideCopy,
			lucideScissors,
			lucideClipboardPaste,
			lucideTrash2,
			lucideLayoutGrid,
			lucideList,
			lucideZoomIn,
			lucideZoomOut,
			lucideUser,
			lucideCreditCard,
			lucideCog,
			lucideBell,
			lucideCircleHelp,
			lucideCalculator,
			lucideCalendar,
			lucideImage,
			lucideCode,
		}),
	],

	template: `
		<div class="mx-auto flex max-w-screen-sm items-center justify-center space-x-4 py-20 text-sm">
			<button hlmBtn variant="outline" (click)="stateChanged('open')">Open Menu</button>
		</div>
		<hlm-command-dialog [state]="state()" (stateChange)="stateChanged($event)">
			<hlm-command>
				<hlm-command-input placeholder="Type a command or search..." />

				<hlm-command-list>
					<div *hlmCommandEmptyState hlmCommandEmpty>No results found.</div>

					<!-- Navigation -->
					<hlm-command-group>
						<hlm-command-group-label>Navigation</hlm-command-group-label>

						<button hlm-command-item value="home" (selected)="commandSelected('home')">
							<ng-icon name="lucideHouse" />
							Home
							<hlm-command-shortcut>⌘H</hlm-command-shortcut>
						</button>

						<button hlm-command-item value="inbox" (selected)="commandSelected('inbox')">
							<ng-icon name="lucideInbox" />
							Inbox
							<hlm-command-shortcut>⌘I</hlm-command-shortcut>
						</button>

						<button hlm-command-item value="documents" (selected)="commandSelected('documents')">
							<ng-icon name="lucideFileText" />
							Documents
							<hlm-command-shortcut>⌘D</hlm-command-shortcut>
						</button>

						<button hlm-command-item value="folders" (selected)="commandSelected('folders')">
							<ng-icon name="lucideFolder" />
							Folders
							<hlm-command-shortcut>⌘F</hlm-command-shortcut>
						</button>
					</hlm-command-group>

					<hlm-command-separator />

					<!-- Actions -->
					<hlm-command-group>
						<hlm-command-group-label>Actions</hlm-command-group-label>

						<button hlm-command-item value="new-file" (selected)="commandSelected('new-file')">
							<ng-icon name="lucidePlus" />
							New File
							<hlm-command-shortcut>⌘N</hlm-command-shortcut>
						</button>

						<button hlm-command-item value="new-folder" (selected)="commandSelected('new-folder')">
							<ng-icon name="lucideFolderPlus" />
							New Folder
							<hlm-command-shortcut>⇧⌘N</hlm-command-shortcut>
						</button>

						<button hlm-command-item value="copy" (selected)="commandSelected('copy')">
							<ng-icon name="lucideCopy" />
							Copy
							<hlm-command-shortcut>⌘C</hlm-command-shortcut>
						</button>

						<button hlm-command-item value="cut" (selected)="commandSelected('cut')">
							<ng-icon name="lucideScissors" />
							Cut
							<hlm-command-shortcut>⌘X</hlm-command-shortcut>
						</button>

						<button hlm-command-item value="paste" (selected)="commandSelected('paste')">
							<ng-icon name="lucideClipboardPaste" />
							Paste
							<hlm-command-shortcut>⌘V</hlm-command-shortcut>
						</button>

						<button hlm-command-item value="delete" (selected)="commandSelected('delete')">
							<ng-icon name="lucideTrash2" />
							Delete
							<hlm-command-shortcut>⌫</hlm-command-shortcut>
						</button>
					</hlm-command-group>

					<hlm-command-separator />

					<!-- View -->
					<hlm-command-group>
						<hlm-command-group-label>View</hlm-command-group-label>

						<button hlm-command-item value="grid-view" (selected)="commandSelected('grid-view')">
							<ng-icon name="lucideLayoutGrid" />
							Grid View
						</button>

						<button hlm-command-item value="list-view" (selected)="commandSelected('list-view')">
							<ng-icon name="lucideList" />
							List View
						</button>

						<button hlm-command-item value="zoom-in" (selected)="commandSelected('zoom-in')">
							<ng-icon name="lucideZoomIn" />
							Zoom In
							<hlm-command-shortcut>⌘+</hlm-command-shortcut>
						</button>

						<button hlm-command-item value="zoom-out" (selected)="commandSelected('zoom-out')">
							<ng-icon name="lucideZoomOut" />
							Zoom Out
							<hlm-command-shortcut>⌘-</hlm-command-shortcut>
						</button>
					</hlm-command-group>

					<hlm-command-separator />

					<!-- Account -->
					<hlm-command-group>
						<hlm-command-group-label>Account</hlm-command-group-label>

						<button hlm-command-item value="profile" (selected)="commandSelected('profile')">
							<ng-icon name="lucideUser" />
							Profile
							<hlm-command-shortcut>⌘P</hlm-command-shortcut>
						</button>

						<button hlm-command-item value="billing" (selected)="commandSelected('billing')">
							<ng-icon name="lucideCreditCard" />
							Billing
							<hlm-command-shortcut>⌘B</hlm-command-shortcut>
						</button>

						<button hlm-command-item value="settings" (selected)="commandSelected('settings')">
							<ng-icon name="lucideCog" />
							Settings
							<hlm-command-shortcut>⌘S</hlm-command-shortcut>
						</button>

						<button hlm-command-item value="notifications" (selected)="commandSelected('notifications')">
							<ng-icon name="lucideBell" />
							Notifications
						</button>

						<button hlm-command-item value="help" (selected)="commandSelected('help')">
							<ng-icon name="lucideCircleHelp" />
							Help & Support
						</button>
					</hlm-command-group>

					<hlm-command-separator />

					<!-- Tools -->
					<hlm-command-group>
						<hlm-command-group-label>Tools</hlm-command-group-label>

						<button hlm-command-item value="calculator" (selected)="commandSelected('calculator')">
							<ng-icon name="lucideCalculator" />
							Calculator
						</button>

						<button hlm-command-item value="calendar" (selected)="commandSelected('calendar')">
							<ng-icon name="lucideCalendar" />
							Calendar
						</button>

						<button hlm-command-item value="image-editor" (selected)="commandSelected('image-editor')">
							<ng-icon name="lucideImage" />
							Image Editor
						</button>

						<button hlm-command-item value="code-editor" (selected)="commandSelected('code-editor')">
							<ng-icon name="lucideCode" />
							Code Editor
						</button>
					</hlm-command-group>
				</hlm-command-list>
			</hlm-command>
		</hlm-command-dialog>
	`,
})
export class CommandScrollable {
	public readonly command = signal('');
	public readonly state = signal<'closed' | 'open'>('closed');

	stateChanged(state: 'open' | 'closed') {
		this.state.set(state);
	}

	commandSelected(selected: string) {
		this.state.set('closed');
		this.command.set(selected);
	}
}

RTL

To enable RTL support in spartan-ng, see the RTL configuration guide.

import { Component, computed, inject } from '@angular/core';
import { provideIcons } from '@ng-icons/core';
import {
	lucideCalculator,
	lucideCalendar,
	lucideCog,
	lucidePlus,
	lucideSearch,
	lucideSmile,
	lucideUser,
	lucideWallet,
} from '@ng-icons/lucide';
import { TranslateService, Translations } from '@spartan-ng/app/app/shared/translate.service';
import { HlmCard, HlmCardImports } from '@spartan-ng/helm/card';
import { HlmCommandImports } from '@spartan-ng/helm/command';
import { HlmIconImports } from '@spartan-ng/helm/icon';

@Component({
	selector: 'spartan-command-rtl',
	imports: [HlmCommandImports, HlmIconImports, HlmCardImports],
	providers: [
		provideIcons({
			lucideSearch,
			lucideCalendar,
			lucideSmile,
			lucidePlus,
			lucideUser,
			lucideWallet,
			lucideCog,
			lucideCalculator,
		}),
	],
	hostDirectives: [HlmCard],
	host: {
		class: 'w-full py-0',
		'[attr.dir]': '_dir()',
	},
	template: `
		<div hlmCardContent class="p-0">
			<hlm-command>
				<hlm-command-input [placeholder]="_t()['placeholder']" />
				<hlm-command-list>
					<div *hlmCommandEmptyState hlmCommandEmpty>{{ _t()['empty'] }}</div>
					<hlm-command-group>
						<hlm-command-group-label>{{ _t()['suggestions'] }}</hlm-command-group-label>
						<button hlm-command-item value="Calendar">
							<ng-icon name="lucideCalendar" />
							{{ _t()['calendar'] }}
						</button>
						<button hlm-command-item value="Search Emoji">
							<ng-icon name="lucideSmile" />
							{{ _t()['searchEmoji'] }}
						</button>
						<button hlm-command-item value="Calculator" disabled>
							<ng-icon name="lucideCalculator" />
							{{ _t()['calculator'] }}
						</button>
					</hlm-command-group>

					<hlm-command-separator />

					<hlm-command-group>
						<hlm-command-group-label>{{ _t()['settings'] }}</hlm-command-group-label>

						<button hlm-command-item value="Profile">
							<ng-icon name="lucideUser" />
							{{ _t()['profile'] }}
							<hlm-command-shortcut>⌘P</hlm-command-shortcut>
						</button>
						<button hlm-command-item value="Billing">
							<ng-icon name="lucideWallet" />
							{{ _t()['billing'] }}
							<hlm-command-shortcut>⌘B</hlm-command-shortcut>
						</button>
						<button hlm-command-item value="Settings">
							<ng-icon name="lucideCog" />
							{{ _t()['settings'] }}
							<hlm-command-shortcut>⌘S</hlm-command-shortcut>
						</button>
					</hlm-command-group>
				</hlm-command-list>
			</hlm-command>
		</div>
	`,
})
export class CommandRtl {
	private readonly _language = inject(TranslateService).language;
	private readonly _translations: Translations = {
		en: {
			dir: 'ltr',
			values: {
				placeholder: 'Type a command or search...',
				empty: 'No results found.',
				suggestions: 'Suggestions',
				calendar: 'Calendar',
				searchEmoji: 'Search Emoji',
				calculator: 'Calculator',
				settings: 'Settings',
				profile: 'Profile',
				billing: 'Billing',
			},
		},
		ar: {
			dir: 'rtl',
			values: {
				placeholder: 'اكتب أمرًا أو ابحث...',
				empty: 'لم يتم العثور على نتائج.',
				suggestions: 'اقتراحات',
				calendar: 'التقويم',
				searchEmoji: 'البحث عن الرموز التعبيرية',
				calculator: 'الآلة الحاسبة',
				settings: 'الإعدادات',
				profile: 'الملف الشخصي',
				billing: 'الفوترة',
			},
		},
		he: {
			dir: 'rtl',
			values: {
				placeholder: 'הקלד פקודה או חפש...',
				empty: 'לא נמצאו תוצאות.',
				suggestions: 'הצעות',
				calendar: 'לוח שנה',
				searchEmoji: "חפש אמוג'י",
				calculator: 'מחשבון',
				settings: 'הגדרות',
				profile: 'פרופיל',
				billing: 'חיוב',
			},
		},
	};

	private readonly _translation = computed(() => this._translations[this._language()]);
	protected readonly _t = computed(() => this._translation().values);
	protected readonly _dir = computed(() => this._translation().dir);
}

Brain API

BrnCommandEmpty

Selector: [brnCommandEmpty]

BrnCommandGroup

Selector: [brnCommandGroup]

Inputs

Prop	Type	Default	Description
id	string	`brn-command-group-${++BrnCommandGroup._id}`	The id of the command list

BrnCommandInput

Selector: input[brnCommandInput]

Inputs

Prop	Type	Default	Description
id	string	this._initialId	The id of the command input

BrnCommandItem

Selector: button[brnCommandItem]

Inputs

Prop	Type	Default	Description
id	string	`brn-command-item-${++BrnCommandItem._id}`	A unique id for the item
value* (required)	string	-	The value this item represents.
disabled	boolean	false	Whether the item is disabled.

Outputs

Prop	Type	Default	Description
selected	void	-	Emits when the item is selected.

BrnCommandList

Selector: [brnCommandList]

Inputs

Prop	Type	Default	Description
id	string	`brn-command-list-${++BrnCommandList._id}`	The id of the command list

BrnCommandSeparator

Selector: [brnCommandSeparator]

BrnCommand

Selector: [brnCommand]

Inputs

Prop	Type	Default	Description
id	string	`brn-command-${++BrnCommand._id}`	The id of the command
filter	CommandFilter	this._config.filter	A custom filter function to use when searching.
disabled	boolean	false	Whether the command is disabled
search	string	-	The current search query.

Outputs

Prop	Type	Default	Description
valueChange	string	-	when the selection has changed
searchChange	string	-	The current search query.

Helm API

HlmCommandDialog

Selector: hlm-command-dialog

Inputs

Prop	Type	Default	Description
title	string	Command Palette	-
description	string	Search for a command to run...	-
state	BrnDialogState	closed	-
showCloseButton	boolean	false	-
dialogContentClass	ClassValue	-	-

Outputs

Prop	Type	Default	Description
stateChange	BrnDialogState	-	-

HlmCommandEmptyState

Selector: [hlmCommandEmptyState]

HlmCommandEmpty

Selector: [hlmCommandEmpty]

HlmCommandGroupLabel

Selector: [hlmCommandGroupLabel],hlm-command-group-label

HlmCommandGroup

Selector: [hlmCommandGroup],hlm-command-group

HlmCommandInput

Selector: hlm-command-input

Inputs

Prop	Type	Default	Description
inputId	string \| undefined	-	-
placeholder	string	-	-

HlmCommandItem

Selector: button[hlmCommandItem],button[hlm-command-item]

HlmCommandList

Selector: [hlmCommandList],hlm-command-list

HlmCommandSeparator

Selector: [hlmCommandSeparator],hlm-command-separator

HlmCommandShortcut

Selector: [hlmCommandShortcut],hlm-command-shortcut

HlmCommand

Selector: [hlmCommand],hlm-command

Context Menu

Combobox

On This Page

Stop configuring. Start shipping.

Zerops powers spartan.ng and Angular teams worldwide.

One-command deployment. Zero infrastructure headaches.

Command

Installation

1 Copy utils if needed

2 Copy and paste the following code into your project.

Usage

Examples

Basic

Shortcuts

Groups

Scrollable

RTL

Brain API

BrnCommandEmpty

BrnCommandGroup

Inputs

BrnCommandInput

Inputs

BrnCommandItem

Inputs

Outputs

BrnCommandList

Inputs

BrnCommandSeparator

BrnCommand

Inputs

Outputs

Helm API

HlmCommandDialog

Inputs

Outputs

HlmCommandEmptyState

HlmCommandEmpty

HlmCommandGroupLabel

HlmCommandGroup

HlmCommandInput

Inputs

HlmCommandItem

HlmCommandList

HlmCommandSeparator

HlmCommandShortcut

HlmCommand