CascadeSelect

Usage

Each parent opens its children. The model changes only when a selectable leaf is chosen. The default node shape contains label, value and optional children; accessors support other domain shapes.

Use the back action or the breadcrumb to move between levels without inventing a second selection value.

Signal Forms

Bind FormField to the value-owning control and add required to the form schema. Select a destination, leave the field to mark it touched, and reset it to check both value and validation state. A required marker on its own does not validate your form.

Signal Forms guide

Try and configure

Change the settings below and interact with the live control. The preview, current application value and generated template stay together. A disabled destination lets you check that unavailable choices cannot be selected.

null

<neu-cascade-select
  (opened)="record('opened', $event)"
  (closed)="record('closed', $event)"
  (groupChange)="record('groupChange', $event)"
  (optionActivated)="record('optionActivated', $event)"
  (touch)="record('touch', $event)"
  (valueChange)="record('valueChange', $event)"
  [options]="destinations"
  [(value)]="destination"
  [clearable]="true"
  [backAriaLabel]="'Back'"
  [breadcrumbAriaLabel]="'Destination path'"
  [emptyLabel]="'No destinations'"
  [label]="'Destination'"
  [placeholder]="'Choose a destination'"
  [rootLabel]="'Destinations'"
/>

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

export const destinations = [
  {
    "value": "eu",
    "label": "Europe",
    "children": [
      {
        "value": "madrid",
        "label": "Madrid"
      },
      {
        "value": "lisbon",
        "label": "Lisbon"
      },
      {
        "value": "paris",
        "label": "Paris"
      },
      {
        "value": "rome",
        "label": "Rome",
        "disabled": true
      }
    ]
  },
  {
    "value": "americas",
    "label": "Americas",
    "children": [
      {
        "value": "bogota",
        "label": "Bogotá"
      },
      {
        "value": "lima",
        "label": "Lima"
      }
    ]
  }
];

export const destination = signal(null);

Value and events

Use one source of truth: [(value)]="destination" or [value]="destination()" with (valueChange)="destination.set($event)". Do not bind both forms at once.

Inputs configure the control. valueChange synchronizes its model; the other Outputs report their documented actions or lifecycle. Requests for suggestions, children or remote windows require the application to supply data.

Accessibility and keyboard

Use a visible label or an accessible name. Test keyboard navigation, disabled options, selection and closing the panel. Custom option templates should keep descriptive text and must not introduce a nested button or another focusable checkbox inside the option.

API

The reference lists the public Inputs, models, Outputs and Templates from the pinned Core package. Click a named type to open its definition. Each applicable Template has an executable example and its actual source.

Inputs

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

Models

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

Outputs

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

import { NeuCascadeSelectEmptyDirective } from '@neural-ui/core/cascade-select';

// Public declaration (reference only)
export declare class NeuCascadeSelectEmptyDirective {
}

import { NeuCascadeSelectEmptyDirective } from '@neural-ui/core/cascade-select';

// Public declaration (reference only)
readonly templateRef: TemplateRef<void>;

import { NeuCascadeSelectFooterDirective } from '@neural-ui/core/cascade-select';

// Public declaration (reference only)
export declare class NeuCascadeSelectFooterDirective {
}

import { NeuCascadeSelectFooterDirective } from '@neural-ui/core/cascade-select';

// Public declaration (reference only)
readonly templateRef: TemplateRef<void>;

import { NeuCascadeSelectHeaderDirective } from '@neural-ui/core/cascade-select';

// Public declaration (reference only)
export declare class NeuCascadeSelectHeaderDirective {
}

import { NeuCascadeSelectHeaderDirective } from '@neural-ui/core/cascade-select';

// Public declaration (reference only)
readonly templateRef: TemplateRef<void>;

import { NeuCascadeSelectItemDirective } from '@neural-ui/core/cascade-select';

// Public declaration (reference only)
export declare class NeuCascadeSelectItemDirective<T> {
}

import type { NeuCascadeSelectItemContext } from '@neural-ui/core/cascade-select';

import { NeuCascadeSelectItemDirective } from '@neural-ui/core/cascade-select';

// Public declaration (reference only)
readonly templateRef: TemplateRef<NeuCascadeSelectItemContext<T>>;

import { NeuCascadeSelectSelectedDirective } from '@neural-ui/core/cascade-select';

// Public declaration (reference only)
export declare class NeuCascadeSelectSelectedDirective<T> {
}

import type { NeuCascadeSelectSelectedContext } from '@neural-ui/core/cascade-select';

import { NeuCascadeSelectSelectedDirective } from '@neural-ui/core/cascade-select';

// Public declaration (reference only)
readonly templateRef: TemplateRef<NeuCascadeSelectSelectedContext<T>>;

Public Types

Open a type to inspect its definition and interface fields.

import type { NeuCascadeSelectItemContext } from '@neural-ui/core/cascade-select';

// Public declaration (reference only)
export interface NeuCascadeSelectItemContext<T> {
  $implicit: T;
  depth: number;
  hasChildren: boolean;
}

import type { NeuCascadeSelectNode } from '@neural-ui/core/cascade-select';

// Public declaration (reference only)
export interface NeuCascadeSelectNode<V = string> {
  children?: readonly NeuCascadeSelectNode<V>[];
  data?: unknown;
  disabled?: boolean;
  label: string;
  value: V;
}

import type { NeuCascadeSelectSelectedContext } from '@neural-ui/core/cascade-select';

// Public declaration (reference only)
export interface NeuCascadeSelectSelectedContext<T> {
  $implicit: T | null;
}

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);

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;
}

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>;

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>;

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}`;

Styles and tokens

Load Core styles once. Use the public tokens below for local customization or a preset for application-wide changes. Keep labels, focus, selected options and disabled states readable in both light and dark themes.

Related components

Choose the control according to the interaction: a visible list, a search field, a hierarchy or an exclusive set of options.

• Select
• Autocomplete
• TreeSelect