Getting Started
UI
Components
- Accordion
- Alert
- Alert Dialog
- Aspect Ratio
- Attachment
- Autocomplete
- Avatar
- Badge
- Breadcrumb
- Bubble
- Button
- Button Group
- Calendar
- Card
- Carousel
- Chart
- Checkbox
- Code Block
- Collapsible
- Combobox
- Command
- Context Menu
- Data Table
- Date Picker
- Dialog
- Drawer
- Dropdown Menu
- Empty
- Field
- Hover Card
- Input Group
- Input OTP
- Input
- Item
- Kbd
- Label
- Marker
- Menubar
- Message
- Message Scroller
- Native Select
- Navigation Menu
- Pagination
- Popover
- Progress
- Questionnaire
- Radio Group
- Resizable
- Scroll Area
- Select
- Separator
- Sheet
- Sidebar
- Skeleton
- Slider
- Sonner (Toast)
- Spinner
- Switch
- Table
- Tabs
- Textarea
- Toggle
- Toggle Group
- Tooltip
- Trace
Utilities
Forms
Stack
Toggle
A two-state button that can be either on or off.
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { lucideBookmark } from '@ng-icons/lucide';
import { HlmToggleImports } from '@spartan-ng/helm/toggle';
@Component({
selector: 'spartan-toggle-preview',
imports: [HlmToggleImports, NgIcon],
providers: [provideIcons({ lucideBookmark })],
changeDetection: ChangeDetectionStrategy.OnPush,
template: `
<button
hlmToggle
size="sm"
variant="outline"
aria-label="Toggle bookmark"
class="data-[state=on]:*:[ng-icon]:*:[svg]:fill-foreground data-[state=on]:bg-transparent"
>
<ng-icon name="lucideBookmark" />
Bookmark
</button>
`,
})
export class TogglePreview {}Installation
ng g @spartan-ng/cli:ui togglenx g @spartan-ng/cli:ui toggleimport { OVERLAY_DEFAULT_CONFIG } from '@angular/cdk/overlay';
import { brnClasses, type BrnClassesOptions } from '@spartan-ng/brain/core';
import { cn, type ClassValue } from 'cn';
import { createCn } from 'cn/config';
import { makeEnvironmentProviders, type EnvironmentProviders } from '@angular/core';
import { provideSpartanHlm } from '@spartan-ng/helm/utils';
/**
* Merges class values and resolves Tailwind CSS conflicts.
*
* To customize the merge (e.g. register custom theme values), create your own instance:
*
* @example
* ```ts
*
*
* export const hlm = createCn({
* extend: { classGroups: { 'font-size': [{ text: ['hero'] }] } },
* });
* ```
*/
export const hlm = cn;
/**
* 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.
* The classes are merged with `hlm`.
*/
export function classes(computed: () => ClassValue[] | string, options: Omit<BrnClassesOptions, 'merge'> = {}) {
brnClasses(computed, { ...options, merge: hlm });
}
/**
* Provides default configuration for Spartan Helm components.
*
* This utility configures the Angular CDK overlay to disable the `usePopover`
* behavior introduced in Angular 21, which causes CDK overlay-based components
* (sheets, dialogs, tooltips, etc.) to render above `position: fixed` elements
* like `<hlm-toaster>`.
*
* @returns {EnvironmentProviders} Environment providers to be added to the application config.
*
* @example
* ```ts
* // app.config.ts
*
*
* export const appConfig: ApplicationConfig = {
* providers: [
* provideSpartanHlm(),
* // ... other providers
* ],
* };
* ```
*/
export function provideSpartanHlm(): EnvironmentProviders {
return makeEnvironmentProviders([
{
provide: OVERLAY_DEFAULT_CONFIG,
useValue: { usePopover: false },
},
]);
}import { BrnToggle } from '@spartan-ng/brain/toggle';
import { Directive, input } from '@angular/core';
import { classes } from '@spartan-ng/helm/utils';
import { cva, type VariantProps } from 'class-variance-authority';
export const toggleVariants = cva(
"hover:text-foreground aria-pressed:bg-muted focus-visible:border-ring focus-visible:ring-ring/50 data-[matches-spartan-invalid=true]:ring-destructive/20 dark:data-[matches-spartan-invalid=true]:ring-destructive/40 data-[matches-spartan-invalid=true]:border-destructive data-[state=on]:bg-muted gap-1 rounded-lg text-sm font-medium transition-all [&_ng-icon:not([class*='text-'])]:text-[length:--spacing(4)] group/toggle hover:bg-muted inline-flex items-center justify-center whitespace-nowrap outline-none focus-visible:ring-[3px] disabled:pointer-events-none disabled:opacity-50 [&_ng-icon]:pointer-events-none [&_ng-icon]:shrink-0",
{
variants: {
variant: {
default: 'bg-transparent',
outline: 'border-input hover:bg-muted border bg-transparent',
},
size: {
default: 'h-8 min-w-8 px-2.5',
sm: "h-7 min-w-7 rounded-[min(var(--radius-md),12px)] px-2.5 text-[0.8rem] [&_ng-icon:not([class*='text-'])]:text-[length:--spacing(3.5)]",
lg: 'h-9 min-w-9 px-2.5',
},
},
defaultVariants: {
variant: 'default',
size: 'default',
},
},
);
export type ToggleVariants = VariantProps<typeof toggleVariants>;
@Directive({
selector: 'button[hlmToggle]',
exportAs: 'hlmToggle',
hostDirectives: [
{
directive: BrnToggle,
inputs: ['id', 'value', 'disabled', 'state', 'aria-label', 'type'],
outputs: ['stateChange'],
},
],
host: {
'data-slot': 'toggle',
},
})
export class HlmToggle {
public readonly variant = input<ToggleVariants['variant']>('default');
public readonly size = input<ToggleVariants['size']>('default');
constructor() {
classes(() =>
toggleVariants({
variant: this.variant(),
size: this.size(),
}),
);
}
}
export const HlmToggleImports = [HlmToggle] as const;import { BrnToggle } from '@spartan-ng/brain/toggle';
import { Directive, input } from '@angular/core';
import { classes } from '@spartan-ng/helm/utils';
import { cva, type VariantProps } from 'class-variance-authority';
export const toggleVariants = cva(
"hover:text-foreground aria-pressed:bg-muted focus-visible:border-ring focus-visible:ring-ring/50 data-[matches-spartan-invalid=true]:ring-destructive/20 dark:data-[matches-spartan-invalid=true]:ring-destructive/40 data-[matches-spartan-invalid=true]:border-destructive dark:data-[matches-spartan-invalid=true]:border-destructive/50 gap-1 rounded-md text-sm font-medium transition-[color,box-shadow] [&_ng-icon:not([class*='text-'])]:text-[length:--spacing(4)] group/toggle hover:bg-muted inline-flex items-center justify-center whitespace-nowrap outline-none focus-visible:ring-[3px] disabled:pointer-events-none disabled:opacity-50 [&_ng-icon]:pointer-events-none [&_ng-icon]:shrink-0",
{
variants: {
variant: {
default: 'bg-transparent',
outline: 'border-input hover:bg-muted border bg-transparent shadow-xs',
},
size: {
default: 'h-9 min-w-9 px-2.5',
sm: 'h-8 min-w-8 px-2.5',
lg: 'h-10 min-w-10 px-2.5',
},
},
defaultVariants: {
variant: 'default',
size: 'default',
},
},
);
export type ToggleVariants = VariantProps<typeof toggleVariants>;
@Directive({
selector: 'button[hlmToggle]',
exportAs: 'hlmToggle',
hostDirectives: [
{
directive: BrnToggle,
inputs: ['id', 'value', 'disabled', 'state', 'aria-label', 'type'],
outputs: ['stateChange'],
},
],
host: {
'data-slot': 'toggle',
},
})
export class HlmToggle {
public readonly variant = input<ToggleVariants['variant']>('default');
public readonly size = input<ToggleVariants['size']>('default');
constructor() {
classes(() =>
toggleVariants({
variant: this.variant(),
size: this.size(),
}),
);
}
}
export const HlmToggleImports = [HlmToggle] as const;import { BrnToggle } from '@spartan-ng/brain/toggle';
import { Directive, input } from '@angular/core';
import { classes } from '@spartan-ng/helm/utils';
import { cva, type VariantProps } from 'class-variance-authority';
export const toggleVariants = cva(
"hover:text-foreground aria-pressed:bg-muted focus-visible:border-ring focus-visible:ring-ring/50 data-[matches-spartan-invalid=true]:ring-destructive/20 dark:data-[matches-spartan-invalid=true]:ring-destructive/40 data-[matches-spartan-invalid=true]:border-destructive data-[state=on]:bg-muted gap-1 rounded-none text-xs font-medium transition-all [&_ng-icon:not([class*='text-'])]:text-[length:--spacing(4)] group/toggle hover:bg-muted inline-flex items-center justify-center whitespace-nowrap outline-none focus-visible:ring-[3px] disabled:pointer-events-none disabled:opacity-50 [&_ng-icon]:pointer-events-none [&_ng-icon]:shrink-0",
{
variants: {
variant: {
default: 'bg-transparent',
outline: 'border-input hover:bg-muted border bg-transparent',
},
size: {
default: 'h-8 min-w-8 px-2.5',
sm: 'h-7 min-w-7 rounded-none px-2.5',
lg: 'h-9 min-w-9 px-2.5',
},
},
defaultVariants: {
variant: 'default',
size: 'default',
},
},
);
export type ToggleVariants = VariantProps<typeof toggleVariants>;
@Directive({
selector: 'button[hlmToggle]',
exportAs: 'hlmToggle',
hostDirectives: [
{
directive: BrnToggle,
inputs: ['id', 'value', 'disabled', 'state', 'aria-label', 'type'],
outputs: ['stateChange'],
},
],
host: {
'data-slot': 'toggle',
},
})
export class HlmToggle {
public readonly variant = input<ToggleVariants['variant']>('default');
public readonly size = input<ToggleVariants['size']>('default');
constructor() {
classes(() =>
toggleVariants({
variant: this.variant(),
size: this.size(),
}),
);
}
}
export const HlmToggleImports = [HlmToggle] as const;import { BrnToggle } from '@spartan-ng/brain/toggle';
import { Directive, input } from '@angular/core';
import { classes } from '@spartan-ng/helm/utils';
import { cva, type VariantProps } from 'class-variance-authority';
export const toggleVariants = cva(
"hover:text-foreground aria-pressed:bg-muted focus-visible:border-ring focus-visible:ring-ring/50 data-[matches-spartan-invalid=true]:ring-destructive/20 dark:data-[matches-spartan-invalid=true]:ring-destructive/40 data-[matches-spartan-invalid=true]:border-destructive gap-1 rounded-4xl text-sm font-medium transition-colors [&_ng-icon:not([class*='text-'])]:text-[length:--spacing(4)] group/toggle hover:bg-muted inline-flex items-center justify-center whitespace-nowrap outline-none focus-visible:ring-[3px] disabled:pointer-events-none disabled:opacity-50 [&_ng-icon]:pointer-events-none [&_ng-icon]:shrink-0",
{
variants: {
variant: {
default: 'bg-transparent',
outline: 'border-input hover:bg-muted border bg-transparent',
},
size: {
default: 'h-9 min-w-9 px-3',
sm: 'h-8 min-w-8 px-3',
lg: 'h-10 min-w-10 px-4',
},
},
defaultVariants: {
variant: 'default',
size: 'default',
},
},
);
export type ToggleVariants = VariantProps<typeof toggleVariants>;
@Directive({
selector: 'button[hlmToggle]',
exportAs: 'hlmToggle',
hostDirectives: [
{
directive: BrnToggle,
inputs: ['id', 'value', 'disabled', 'state', 'aria-label', 'type'],
outputs: ['stateChange'],
},
],
host: {
'data-slot': 'toggle',
},
})
export class HlmToggle {
public readonly variant = input<ToggleVariants['variant']>('default');
public readonly size = input<ToggleVariants['size']>('default');
constructor() {
classes(() =>
toggleVariants({
variant: this.variant(),
size: this.size(),
}),
);
}
}
export const HlmToggleImports = [HlmToggle] as const;import { BrnToggle } from '@spartan-ng/brain/toggle';
import { Directive, input } from '@angular/core';
import { classes } from '@spartan-ng/helm/utils';
import { cva, type VariantProps } from 'class-variance-authority';
export const toggleVariants = cva(
"hover:text-foreground aria-pressed:bg-muted focus-visible:border-ring focus-visible:ring-ring/50 data-[matches-spartan-invalid=true]:ring-destructive/20 dark:data-[matches-spartan-invalid=true]:ring-destructive/40 data-[matches-spartan-invalid=true]:border-destructive data-[state=on]:bg-muted gap-1 rounded-md text-xs font-medium transition-all [&_ng-icon:not([class*='text-'])]:text-[length:--spacing(4)] group/toggle hover:bg-muted inline-flex items-center justify-center whitespace-nowrap outline-none focus-visible:ring-[3px] disabled:pointer-events-none disabled:opacity-50 [&_ng-icon]:pointer-events-none [&_ng-icon]:shrink-0",
{
variants: {
variant: {
default: 'bg-transparent',
outline: 'border-input hover:bg-muted border bg-transparent',
},
size: {
default: 'h-7 min-w-7 px-2',
sm: "h-6 min-w-6 rounded-[min(var(--radius-md),8px)] px-2 text-[0.625rem] [&_ng-icon:not([class*='text-'])]:text-[length:--spacing(3)]",
lg: 'h-8 min-w-8 px-2.5',
},
},
defaultVariants: {
variant: 'default',
size: 'default',
},
},
);
export type ToggleVariants = VariantProps<typeof toggleVariants>;
@Directive({
selector: 'button[hlmToggle]',
exportAs: 'hlmToggle',
hostDirectives: [
{
directive: BrnToggle,
inputs: ['id', 'value', 'disabled', 'state', 'aria-label', 'type'],
outputs: ['stateChange'],
},
],
host: {
'data-slot': 'toggle',
},
})
export class HlmToggle {
public readonly variant = input<ToggleVariants['variant']>('default');
public readonly size = input<ToggleVariants['size']>('default');
constructor() {
classes(() =>
toggleVariants({
variant: this.variant(),
size: this.size(),
}),
);
}
}
export const HlmToggleImports = [HlmToggle] as const;import { BrnToggle } from '@spartan-ng/brain/toggle';
import { Directive, input } from '@angular/core';
import { classes } from '@spartan-ng/helm/utils';
import { cva, type VariantProps } from 'class-variance-authority';
export const toggleVariants = cva(
"hover:text-foreground aria-pressed:bg-muted focus-visible:border-ring focus-visible:ring-ring/30 data-[matches-spartan-invalid=true]:ring-destructive/20 dark:data-[matches-spartan-invalid=true]:ring-destructive/40 data-[matches-spartan-invalid=true]:border-destructive gap-1 rounded-3xl text-sm font-medium transition-colors [&_ng-icon:not([class*='text-'])]:text-[length:--spacing(4)] group/toggle hover:bg-muted inline-flex items-center justify-center whitespace-nowrap outline-none focus-visible:ring-[3px] disabled:pointer-events-none disabled:opacity-50 [&_ng-icon]:pointer-events-none [&_ng-icon]:shrink-0",
{
variants: {
variant: {
default: 'bg-transparent',
outline: 'border-input hover:bg-muted border bg-transparent',
},
size: {
default: 'h-9 min-w-9 px-3',
sm: 'h-8 min-w-8 px-3',
lg: 'h-10 min-w-10 px-4',
},
},
defaultVariants: {
variant: 'default',
size: 'default',
},
},
);
export type ToggleVariants = VariantProps<typeof toggleVariants>;
@Directive({
selector: 'button[hlmToggle]',
exportAs: 'hlmToggle',
hostDirectives: [
{
directive: BrnToggle,
inputs: ['id', 'value', 'disabled', 'state', 'aria-label', 'type'],
outputs: ['stateChange'],
},
],
host: {
'data-slot': 'toggle',
},
})
export class HlmToggle {
public readonly variant = input<ToggleVariants['variant']>('default');
public readonly size = input<ToggleVariants['size']>('default');
constructor() {
classes(() =>
toggleVariants({
variant: this.variant(),
size: this.size(),
}),
);
}
}
export const HlmToggleImports = [HlmToggle] as const;Usage
import { HlmToggleImports } from '@spartan-ng/helm/toggle';<button hlmToggle>Toggle</button>Examples
Outline
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { lucideBold, lucideItalic } from '@ng-icons/lucide';
import { HlmToggleImports } from '@spartan-ng/helm/toggle';
@Component({
selector: 'spartan-toggle-outline',
imports: [HlmToggleImports, NgIcon],
providers: [provideIcons({ lucideItalic, lucideBold })],
changeDetection: ChangeDetectionStrategy.OnPush,
template: `
<div class="flex flex-wrap items-center gap-2">
<button hlmToggle variant="outline" aria-label="Toggle Italic">
<ng-icon name="lucideItalic" />
Italic
</button>
<button hlmToggle variant="outline" aria-label="Toggle Bold">
<ng-icon name="lucideBold" />
Bold
</button>
</div>
`,
})
export class ToggleOutlinePreview {}With Text
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { lucideItalic } from '@ng-icons/lucide';
import { HlmToggleImports } from '@spartan-ng/helm/toggle';
@Component({
selector: 'spartan-toggle-with-text',
imports: [HlmToggleImports, NgIcon],
providers: [provideIcons({ lucideItalic })],
changeDetection: ChangeDetectionStrategy.OnPush,
template: `
<button hlmToggle aria-label="Toggle italic">
<ng-icon name="lucideItalic" />
Italic
</button>
`,
})
export class ToggleWithTextPreview {}Size
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { HlmToggleImports } from '@spartan-ng/helm/toggle';
@Component({
selector: 'spartan-toggle-size',
imports: [HlmToggleImports],
changeDetection: ChangeDetectionStrategy.OnPush,
template: `
<div class="flex flex-wrap items-center gap-2">
<button hlmToggle variant="outline" size="sm" aria-label="Toggle small">Small</button>
<button hlmToggle variant="outline" aria-label="Toggle default">Default</button>
<button hlmToggle variant="outline" size="lg" aria-label="Toggle large">Large</button>
</div>
`,
})
export class ToggleSizePreview {}Disabled
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { HlmToggleImports } from '@spartan-ng/helm/toggle';
@Component({
selector: 'spartan-toggle-disabled',
imports: [HlmToggleImports],
changeDetection: ChangeDetectionStrategy.OnPush,
template: `
<div class="flex flex-wrap items-center gap-2">
<button hlmToggle aria-label="Toggle disabled" disabled>Disabled</button>
<button hlmToggle variant="outline" aria-label="Toggle disabled outline" disabled>Disabled</button>
</div>
`,
})
export class ToggleDisabledPreview {}RTL
To enable RTL support in spartan-ng, see the RTL configuration guide.
import { ChangeDetectionStrategy, Component, computed, inject } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { lucideBookmark } from '@ng-icons/lucide';
import { TranslateService, Translations } from '@spartan-ng/app/app/shared/translate.service';
import { HlmToggleImports } from '@spartan-ng/helm/toggle';
@Component({
selector: 'spartan-toggle-rtl',
imports: [HlmToggleImports, NgIcon],
providers: [provideIcons({ lucideBookmark })],
changeDetection: ChangeDetectionStrategy.OnPush,
template: `
<button
hlmToggle
variant="outline"
[aria-label]="_t()['label']"
[dir]="_dir()"
class="data-[state=on]:*:[ng-icon]:*:[svg]:fill-foreground"
>
<ng-icon name="lucideBookmark" />
{{ _t()['label'] }}
</button>
`,
})
export class ToggleRtlPreview {
private readonly _language = inject(TranslateService).language;
private readonly _translations: Translations = {
en: {
dir: 'ltr',
values: {
label: 'Bookmark',
},
},
ar: {
dir: 'rtl',
values: {
label: 'إشارة مرجعية',
},
},
he: {
dir: 'rtl',
values: {
label: 'סימנייה',
},
},
};
private readonly _translation = computed(() => this._translations[this._language()]);
protected readonly _t = computed(() => this._translation().values);
protected readonly _dir = computed(() => this._translation().dir);
}Brain API
BrnToggle
Selector: button[brnToggle]
ExportAs: brnToggle
Inputs
| Prop | Type | Default | Description |
|---|---|---|---|
| id | string | `brn-toggle-${++BrnToggle._uniqueId}` | The id of the toggle. |
| value | T | - | The value this toggle represents. |
| disabled | boolean | false | Whether the toggle is disabled. |
| type | 'button' | 'submit' | 'reset' | 'button' | The type of the button. |
| aria-label | string | null | null | Accessibility label for screen readers. Use when no visible label exists. |
| state | 'on' | 'off' | 'off' | The current state of the toggle when not used in a group. |
Outputs
| Prop | Type | Default | Description |
|---|---|---|---|
| stateChange | 'on' | 'off' | 'off' | The current state of the toggle when not used in a group. |
Helm API
HlmToggle
Selector: button[hlmToggle]
ExportAs: hlmToggle
Inputs
| Prop | Type | Default | Description |
|---|---|---|---|
| variant | ToggleVariants['variant'] | 'default' | - |
| size | ToggleVariants['size'] | 'default' | - |
| id | string | `brn-toggle-${++BrnToggle._uniqueId}` | The id of the toggle. |
| value | T | - | The value this toggle represents. |
| disabled | boolean | false | Whether the toggle is disabled. |
| state | 'on' | 'off' | 'off' | The current state of the toggle when not used in a group. |
| aria-label | string | null | null | Accessibility label for screen readers. Use when no visible label exists. |
| type | 'button' | 'submit' | 'reset' | 'button' | The type of the button. |
Outputs
| Prop | Type | Default | Description |
|---|---|---|---|
| stateChange | 'on' | 'off' | - | The current state of the toggle when not used in a group. |