ToggleButtonGroup | Neural UI v2

Usage

Use mode="single" for a scalar or null; mode="multiple" uses a readonly array. deselectable allows an active option to be cleared. options supports disabled entries and optional application icons. The item Template replaces visual content while Core retains the pressed state and native button.

Examples

Try this application-owned interaction. Its event handling and initial data are included in Code.

Current value: [ "week" ]

Events: 0

Try and configure

Change the public options, try the result and inspect the updated template. Code contains the complete executable implementation.

Current value: "week"

Events: 0

disabled

readonly

invalid

deselectable

Advanced options · 5

<neu-toggle-button-group
  mode="single"
  [options]="options()"
  [value]="value()"
  (valueChange)="acceptValue($event)"
  [size]="'md'"
  [deselectable]="true"
  [disabled]="false"
  [readonly]="false"
  [invalid]="false"
></neu-toggle-button-group>

State and data for this configuration

These values match the current preview. Complete handlers, Core imports and templates are in Source.

import { signal } from '@angular/core';

export const options = signal([
  {
    "label": "Day",
    "value": "day"
  },
  {
    "label": "Week",
    "value": "week"
  },
  {
    "label": "Month",
    "value": "month"
  },
  {
    "label": "Unavailable",
    "value": "none",
    "disabled": true
  }
]);

export const value = signal("week");

Data, callback and structured configuration inputs

These inputs require a model or function, not a checkbox. Edit the same-named field in the Source component and bind it in the template; data already used by this preview appears in the state above.

compareWith · (left: NeuToggleValue<T, V>, right: NeuToggleValue<T, V>) => boolean

In Source: define compareWith with this type and use [compareWith]="compareWith" (or compareWith() for a signal).

errors · readonly ValidationError.WithOptionalFieldTree[]

In Source: define errors with this type and use [errors]="errors" (or errors() for a signal).

optionDisabled · NeuOptionDisabledAccessor<NeuToggleOptionModel<T, V>> | null

In Source: define optionDisabled with this type and use [optionDisabled]="optionDisabled" (or optionDisabled() for a signal).

optionLabel · NeuOptionLabelAccessor<NeuToggleOptionModel<T, V>> | null

In Source: define optionLabel with this type and use [optionLabel]="optionLabel" (or optionLabel() for a signal).

options · readonly NeuToggleOptionModel<T, V>[]

In Source: define options with this type and use [options]="options" (or options() for a signal).

optionValue · (option: NeuToggleOptionModel<T, V>) => NeuToggleValue<T, V>

In Source: define optionValue with this type and use [optionValue]="optionValue" (or optionValue() for a signal).

State and events

Use mode="single" for a scalar or null; mode="multiple" uses a readonly array. deselectable allows an active option to be cleared. options supports disabled entries and optional application icons. The item Template replaces visual content while Core retains the pressed state and native button.

Accessibility and keyboard

Arrow keys move focus between enabled options; Enter/Space select. Tab enters and leaves the group.

Key	Action
`Tab`	Enter or leave the group.
`Arrow keys`	Move focus between available options; horizontal movement follows text direction.
`Home`	Focus the first available option.
`End`	Focus the last available option.
`Enter`	Select the focused option.
`Space`	Select the focused option.

API

Inputs, models and Outputs are extracted from the installed Core package. Named public types link to their definitions. Templates below include executable examples.

Inputs

Configure the component with [property]="value". Your application supplies these values; the component does not replace the state you pass in.

Name	Type	Default	Template binding	Description
`compareWith`	`(left: NeuToggleValue<T, V>, right: NeuToggleValue<T, V>) => boolean`	`Object.is`Derived default	`[compareWith]`	Comparison function for selected values; use stable domain identity.
`deselectable`	`boolean`	`true`	`[deselectable]`	Allow an already selected option to be deselected.
`dirty`	`boolean`	`false`	`[dirty]`	Form state indicating that the user has changed the value.
`disabled`	`boolean`	`false`	`[disabled]`	Prevents interaction with this control.
`errors`	`readonly ValidationError.WithOptionalFieldTree[]`	`[]`	`[errors]`	Validation errors supplied by the form or the application.
`hidden`	`boolean`	`false`	`[hidden]`	Hides the control according to the form state.
`invalid`	`boolean`	`false`	`[invalid]`	Displays the invalid state; it does not add a validation rule.
`mode`	`M`	`'single' as M`Derived default	`[mode]`	single accepts one value; multiple accepts a readonly array of values.
`optionDisabled`	`NeuOptionDisabledAccessor<NeuToggleOptionModel<T, V>> \| null`	`null`	`[optionDisabled]`	Field name or function that marks an option as disabled.
`optionLabel`	`NeuOptionLabelAccessor<NeuToggleOptionModel<T, V>> \| null`	`null`	`[optionLabel]`	Field name or function used to obtain the visible option label.
`options`	`readonly NeuToggleOptionModel<T, V>[]`	`[]`	`[options]`	Loaded option records. Accessors allow using your own domain objects.
`optionValue`	`(option: NeuToggleOptionModel<T, V>) => NeuToggleValue<T, V>`	`(option) => resolveNeuOptionValue<NeuToggleOptionModel<T, V>, NeuToggleValue<T, V>>(option)`Derived default	`[optionValue]`	Field name or function used to obtain the stored option value.
`pending`	`boolean`	`false`	`[pending]`	Form state indicating that asynchronous validation is pending.
`readonly`	`boolean`	`false`	`[readonly]`	Keeps the applied value visible but prevents user edits.
`required`	`boolean`	`false`	`[required]`	Marks the field as required; use a form validator to enforce it.
`size`	`NeuButtonSize`	`'md'`	`[size]`	Control size. The accepted scale or numeric unit is specified by its type.
`touched`	`boolean`	`false`	`[touched]`	Form state indicating that the control has been visited.

Models

A model supports [(property)]="signal" or the [property] and (propertyChange) pair. Choose one form, not both.

Name	Type	Default	Template binding	Description
`value`	`NeuSelectionValue<NeuToggleValue<T, V>, M>`	`null as NeuSelectionValue<NeuToggleValue<T, V>, M>`Derived default	`[(value)]`	Application-owned editable model value.

Outputs

Listen to an event with (event)="handler($event)". The table explains the data your handler receives and how to use it.

Name	Payload	Template binding	Description
`optionActivated`	`NeuOptionActivatedEvent<NeuToggleOptionModel<T, V>, NeuToggleValue<T, V>>`	`(optionActivated)="onOptionActivated($event)"`	Activated option, its value and the originating event.
`touch`	`void`	`(touch)="onTouch($event)"`	Notifies the form that the control has been touched; not a value change.

Templates

ng-content projects content into the component. TemplateRef inputs receive a template; ng-template directives identify templates with a typed context. A directive shared by an entrypoint is not necessarily a slot of this component.

Name	Mechanism	Contract
`NeuToggleButtonItemDirective`View example	Public template directive (entrypoint)	`ng-template[neuToggleButtonItem]`

NeuToggleButtonItemDirectiveView example

Public template directive (entrypoint)

ng-template[neuToggleButtonItem]

Declaration

import { NeuToggleButtonItemDirective } from '@neural-ui/core/toggle-button-group';

// Public declaration (reference only)
export declare class NeuToggleButtonItemDirective<T = unknown, V = NeuToggleValueNotProvided> {
}

Full context

import { NeuToggleButtonItemDirective } from '@neural-ui/core/toggle-button-group';

// Public declaration (reference only)
readonly templateRef: TemplateRef<{
    $implicit: NeuToggleOptionModel<T, V>;
    selected: boolean;
}>;

Each example demonstrates a different template. Switch between Demo and Code to inspect its implementation, imports and state.

NeuToggleButtonItemDirective

NeuToggleButtonItemDirective

Current value: "week"

Events: 0

Public Types

Open a type to inspect its definition and interface fields.

NeuButtonSizeTypeScript

NeuIconKeyTypeScript

NeuOptionAccessorTypeScript

import type { NeuOptionPath } from '@neural-ui/core/option-api';

import type { NeuOptionAccessor } from '@neural-ui/core/option-api';

// Public declaration (reference only)
export type NeuOptionAccessor<T, R = unknown> = Exclude<keyof T, string> | NeuOptionPath<T> | ((option: T) => R);

NeuOptionActivatedEventTypeScript

import type { NeuOptionActivatedEvent } from '@neural-ui/core/option-api';

// Public declaration (reference only)
export interface NeuOptionActivatedEvent<T, V> {
  readonly option: T;
  readonly originalEvent?: Event;
  readonly source: 'pointer' | 'keyboard';
  readonly value: V;
}

NeuOptionDisabledAccessorTypeScript

import type { NeuOptionAccessor } from '@neural-ui/core/option-api';

import type { NeuOptionDisabledAccessor } from '@neural-ui/core/option-api';

// Public declaration (reference only)
export type NeuOptionDisabledAccessor<T> = NeuOptionAccessor<T, boolean>;

NeuOptionLabelAccessorTypeScript

import type { NeuOptionAccessor } from '@neural-ui/core/option-api';

import type { NeuOptionLabelAccessor } from '@neural-ui/core/option-api';

// Public declaration (reference only)
export type NeuOptionLabelAccessor<T> = NeuOptionAccessor<T, string>;

NeuOptionPathTypeScript

import type { NeuOptionPath } from '@neural-ui/core/option-api';

// Public declaration (reference only)
export type NeuOptionPath<T> = Extract<keyof T, string> | `${Extract<keyof T, string>}.${string}`;

NeuSelectionModeTypeScript

NeuSelectionValueTypeScript

import type { NeuSelectionMode } from '@neural-ui/core/option-api';

import type { NeuSelectionValue } from '@neural-ui/core/option-api';

// Public declaration (reference only)
export type NeuSelectionValue<V, M extends NeuSelectionMode> = M extends 'multiple' ? readonly V[] : V | null;

NeuToggleOptionTypeScript

import type { NeuIconKey } from '@neural-ui/core/foundation';

import type { NeuToggleOption } from '@neural-ui/core/toggle-button-group';

// Public declaration (reference only)
export interface NeuToggleOption<T = unknown> {
  disabled?: boolean;
  icon?: NeuIconKey;
  label: string;
  value: T;
}

Styles and tokens

Use the supported public tokens listed below. Surrounding layout belongs to your application; validate the result in light and dark modes and narrow containers.

Specific tokens

This component uses shared theme tokens rather than dedicated component hooks.

Shared tokens used

Override these on a local wrapper to affect this example. An override on :root affects other components that use the same token.

Token	Purpose here	Other impact	Default / fallback
`--neu-border`	Normal control and cell borders	Shared by other Core consumers; scope the override.	`rgba(15, 23, 42, 0.08)`
`--neu-primary`	Brand color for active controls and emphasis	Shared by other Core consumers; scope the override.	`#007aff`
`--neu-primary-dark`	Dark brand shade; outline and ghost Button text in the light theme	Shared by other Core consumers; scope the override.	`#005fcc`
`--neu-primary-fg`	Foreground drawn over the primary background	Shared by other Core consumers; scope the override.	`#ffffff`
`--neu-primary-solid`	Solid brand action background	Shared by other Core consumers; scope the override.	`#006ee6`
`--neu-primary-solid-fg`	Foreground of solid brand actions	Shared by other Core consumers; scope the override.	`#ffffff`
`--neu-primary-solid-hover`	Hover background of solid brand actions	Shared by other Core consumers; scope the override.	`#005fcc`
`--neu-radius`	Control corner radius	Shared by other Core consumers; scope the override.	`8px`

Related components

Use related components when your task requires a different interaction or a composed control.