Grouping

Use the groupBy input to group options by an item key or a function expression.

Group by item key

TypeScript
HTML

import { Component, OnInit, ChangeDetectionStrategy } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { JsonPipe } from '@angular/common';
import { NgOptgroupTemplateDirective, NgSelectComponent } from '@ng-select/ng-select';

@Component({
    selector: 'ng-group-default-example',
    templateUrl: './group-default-example.component.html',
    styleUrls: ['./group-default-example.component.scss'],
    changeDetection: ChangeDetectionStrategy.Eager,
    imports: [NgSelectComponent, FormsModule, NgOptgroupTemplateDirective, JsonPipe],
})
export class GroupDefaultExampleComponent implements OnInit {
    selectedAccount = 'Adam';
    accounts = [
        { name: 'Adam', email: 'adam@email.com', age: 12, country: 'United States', child: { state: 'Active' } },
        { name: 'Homer', email: 'homer@email.com', age: 47, country: '', child: { state: 'Active' } },
        { name: 'Samantha', email: 'samantha@email.com', age: 30, country: 'United States', child: { state: 'Active' } },
        { name: 'Amalie', email: 'amalie@email.com', age: 12, country: 'Argentina', child: { state: 'Active' } },
        { name: 'Estefanía', email: 'estefania@email.com', age: 21, country: 'Argentina', child: { state: 'Active' } },
        { name: 'Adrian', email: 'adrian@email.com', age: 21, country: 'Ecuador', child: { state: 'Active' } },
        { name: 'Wladimir', email: 'wladimir@email.com', age: 30, country: 'Ecuador', child: { state: 'Inactive' } },
        { name: 'Natasha', email: 'natasha@email.com', age: 54, country: 'Ecuador', child: { state: 'Inactive' } },
        { name: 'Nicole', email: 'nicole@email.com', age: 43, country: 'Colombia', child: { state: 'Inactive' } },
        { name: 'Michael', email: 'michael@email.com', age: 15, country: 'Colombia', child: { state: 'Inactive' } },
        { name: 'Nicolás', email: 'nicole@email.com', age: 43, country: 'Colombia', child: { state: 'Inactive' } },
    ];

    constructor() {}

    ngOnInit() {}
}

<p>You can group by item key providing key name as a string to <b>groupBy</b> input</p>

<ng-select [items]="accounts" bindLabel="name" bindValue="name" groupBy="country" [(ngModel)]="selectedAccount">
    <ng-template ng-optgroup-tmp let-item="item">
        {{ item.country || 'Unnamed group' }}
    </ng-template>
</ng-select>

<br />
<small>Selected: {{ selectedAccount | json }}</small>

Group by function expression

TypeScript
HTML

import { Component, OnInit, ChangeDetectionStrategy } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { NgOptgroupTemplateDirective, NgSelectComponent } from '@ng-select/ng-select';
import { JsonPipe } from '@angular/common';

@Component({
    selector: 'ng-group-function-example',
    templateUrl: './group-function-example.component.html',
    styleUrls: ['./group-function-example.component.scss'],
    changeDetection: ChangeDetectionStrategy.Eager,
    imports: [NgSelectComponent, FormsModule, NgOptgroupTemplateDirective, JsonPipe],
})
export class GroupFunctionExampleComponent implements OnInit {
    selectedAccounts = ['Michael'];
    accounts = [
        { name: 'Jill', email: 'jill@email.com', age: 15, country: undefined, child: { state: 'Active' } },
        { name: 'Henry', email: 'henry@email.com', age: 10, country: undefined, child: { state: 'Active' } },
        { name: 'Meg', email: 'meg@email.com', age: 7, country: null, child: { state: 'Active' } },
        { name: 'Adam', email: 'adam@email.com', age: 12, country: 'United States', child: { state: 'Active' } },
        { name: 'Homer', email: 'homer@email.com', age: 47, country: '', child: { state: 'Active' } },
        { name: 'Samantha', email: 'samantha@email.com', age: 30, country: 'United States', child: { state: 'Active' } },
        { name: 'Amalie', email: 'amalie@email.com', age: 12, country: 'Argentina', child: { state: 'Active' } },
        { name: 'Estefanía', email: 'estefania@email.com', age: 21, country: 'Argentina', child: { state: 'Active' } },
        { name: 'Adrian', email: 'adrian@email.com', age: 21, country: 'Ecuador', child: { state: 'Active' } },
        { name: 'Wladimir', email: 'wladimir@email.com', age: 30, country: 'Ecuador', child: { state: 'Inactive' } },
        { name: 'Natasha', email: 'natasha@email.com', age: 54, country: 'Ecuador', child: { state: 'Inactive' } },
        { name: 'Nicole', email: 'nicole@email.com', age: 43, country: 'Colombia', child: { state: 'Inactive' } },
        { name: 'Michael', email: 'michael@email.com', age: 15, country: 'Colombia', child: { state: 'Inactive' } },
        { name: 'Nicolás', email: 'nicole@email.com', age: 43, country: 'Colombia', child: { state: 'Inactive' } },
    ];

    constructor() {}

    groupByFn = (item) => item.child.state;

    groupValueFn = (_: string, children: any[]) => ({ name: children[0].child.state, total: children.length });

    ngOnInit() {}
}

<p>
    Having more complex use case, you can use function expression as <b>groupBy</b> input. Also you can use <b>[groupValue]</b>
    to set value of grouped item.
</p>

<ng-select
    [items]="accounts"
    bindLabel="name"
    bindValue="name"
    [groupBy]="groupByFn"
    [groupValue]="groupValueFn"
    [multiple]="true"
    [(ngModel)]="selectedAccounts">
    <ng-template ng-optgroup-tmp let-item="item">
        <span style="vertical-align: middle">{{ item.name }}</span>
        <span class="ml-1 badge badge-secondary">{{ item.total }}</span>
    </ng-template>
</ng-select>

<br />
<small>Selected: {{ selectedAccounts | json }}</small>

Selectable groups

TypeScript
HTML

import { Component, OnInit, ChangeDetectionStrategy } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { NgOptgroupTemplateDirective, NgSelectComponent } from '@ng-select/ng-select';
import { JsonPipe } from '@angular/common';

@Component({
    selector: 'ng-group-selectable-example',
    templateUrl: './group-selectable-example.component.html',
    styleUrls: ['./group-selectable-example.component.scss'],
    changeDetection: ChangeDetectionStrategy.Eager,
    imports: [NgSelectComponent, FormsModule, NgOptgroupTemplateDirective, JsonPipe],
})
export class GroupSelectableExampleComponent implements OnInit {
    selectedAccount = [{ country: 'Colombia' }];
    selectedAccounts = [{ name: 'Adam' }];
    accounts = [
        { name: 'Jill', email: 'jill@email.com', age: 15, country: undefined, child: { state: 'Active' } },
        { name: 'Henry', email: 'henry@email.com', age: 10, country: undefined, child: { state: 'Active' } },
        { name: 'Meg', email: 'meg@email.com', age: 7, country: null, child: { state: 'Active' } },
        { name: 'Adam', email: 'adam@email.com', age: 12, country: 'United States', child: { state: 'Active' } },
        { name: 'Homer', email: 'homer@email.com', age: 47, country: '', child: { state: 'Active' } },
        { name: 'Samantha', email: 'samantha@email.com', age: 30, country: 'United States', child: { state: 'Active' } },
        { name: 'Amalie', email: 'amalie@email.com', age: 12, country: 'Argentina', child: { state: 'Active' } },
        { name: 'Estefanía', email: 'estefania@email.com', age: 21, country: 'Argentina', child: { state: 'Active' } },
        { name: 'Adrian', email: 'adrian@email.com', age: 21, country: 'Ecuador', child: { state: 'Active' } },
        { name: 'Wladimir', email: 'wladimir@email.com', age: 30, country: 'Ecuador', child: { state: 'Inactive' } },
        { name: 'Natasha', email: 'natasha@email.com', age: 54, country: 'Ecuador', child: { state: 'Inactive' }, disabled: true },
        { name: 'Nicole', email: 'nicole@email.com', age: 43, country: 'Colombia', child: { state: 'Inactive' } },
        { name: 'Michael', email: 'michael@email.com', age: 15, country: 'Colombia', child: { state: 'Inactive' } },
        { name: 'Nicolás', email: 'nicole@email.com', age: 43, country: 'Colombia', child: { state: 'Inactive' } },
    ];

    ngOnInit() {}

    compareAccounts = (item, selected) => {
        if (selected.country && item.country) {
            return item.country === selected.country;
        }
        if (item.name && selected.name) {
            return item.name === selected.name;
        }
        return false;
    };
}

<p>Groups can be made selectable. By default group acts as a separate option.</p>
<ng-select
    [items]="accounts"
    bindLabel="name"
    groupBy="country"
    [multiple]="true"
    [compareWith]="compareAccounts"
    [selectableGroup]="true"
    [(ngModel)]="selectedAccount">
    <ng-template ng-optgroup-tmp let-item="item">
        {{ item.country || 'Unnamed group' }}
    </ng-template>
</ng-select>

<br />
<small>Selected: {{ selectedAccount | json }}</small>
<hr />

<p>Using <b>[selectableGroupAsModel]="false"</b> selecting group will select all of its children but not group itself.</p>

<ng-select
    [items]="accounts"
    bindLabel="name"
    groupBy="country"
    [multiple]="true"
    [closeOnSelect]="false"
    [selectableGroup]="true"
    [selectableGroupAsModel]="false"
    [compareWith]="compareAccounts"
    [(ngModel)]="selectedAccounts">
    <ng-template ng-optgroup-tmp let-item="item">
        {{ item.country || 'Unnamed group' }}
    </ng-template>
</ng-select>

<br />
<small>Selected: {{ selectedAccounts | json }}</small>

Selectable groups with hidden selected items

TypeScript
HTML

import { Component, OnInit, ChangeDetectionStrategy } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { NgOptgroupTemplateDirective, NgSelectComponent } from '@ng-select/ng-select';
import { JsonPipe } from '@angular/common';

@Component({
    selector: 'ng-group-selectable-hidden-example',
    templateUrl: './group-selectable-hidden-example.component.html',
    styleUrls: ['./group-selectable-hidden-example.component.scss'],
    changeDetection: ChangeDetectionStrategy.Eager,
    imports: [NgSelectComponent, FormsModule, NgOptgroupTemplateDirective, JsonPipe],
})
export class GroupSelectableHiddenExampleComponent implements OnInit {
    accounts = [
        { name: 'Jill', email: 'jill@email.com', age: 15, country: undefined, child: { state: 'Active' } },
        { name: 'Henry', email: 'henry@email.com', age: 10, country: undefined, child: { state: 'Active' } },
        { name: 'Meg', email: 'meg@email.com', age: 7, country: null, child: { state: 'Active' } },
        { name: 'Adam', email: 'adam@email.com', age: 12, country: 'United States', child: { state: 'Active' } },
        { name: 'Homer', email: 'homer@email.com', age: 47, country: '', child: { state: 'Active' } },
        { name: 'Samantha', email: 'samantha@email.com', age: 30, country: 'United States', child: { state: 'Active' } },
        { name: 'Amalie', email: 'amalie@email.com', age: 12, country: 'Argentina', child: { state: 'Active' } },
        { name: 'Estefanía', email: 'estefania@email.com', age: 21, country: 'Argentina', child: { state: 'Active' } },
        { name: 'Adrian', email: 'adrian@email.com', age: 21, country: 'Ecuador', child: { state: 'Active' } },
        { name: 'Wladimir', email: 'wladimir@email.com', age: 30, country: 'Ecuador', child: { state: 'Inactive' } },
        { name: 'Natasha', email: 'natasha@email.com', age: 54, country: 'Ecuador', child: { state: 'Inactive' } },
        { name: 'Nicole', email: 'nicole@email.com', age: 43, country: 'Colombia', child: { state: 'Inactive' } },
        { name: 'Michael', email: 'michael@email.com', age: 15, country: 'Colombia', child: { state: 'Inactive' } },
        { name: 'Nicolás', email: 'nicole@email.com', age: 43, country: 'Colombia', child: { state: 'Inactive' } },
    ];

    selectedAccounts = [{ country: 'Argentina' }, { name: 'Samantha' }];

    constructor() {}

    ngOnInit() {}

    compareAccounts = (item, selected) => {
        if (selected.country && item.country) {
            return item.country === selected.country;
        }
        if (item.name && selected.name) {
            return item.name === selected.name;
        }
        return false;
    };
}

<p>Selecting group will hide all of its items</p>

<ng-select
    [items]="accounts"
    bindLabel="name"
    groupBy="country"
    [multiple]="true"
    [hideSelected]="true"
    [closeOnSelect]="false"
    [selectableGroup]="true"
    [compareWith]="compareAccounts"
    [(ngModel)]="selectedAccounts">
    <ng-template ng-optgroup-tmp let-item="item">
        {{ item.country || 'Unnamed group' }}
    </ng-template>
</ng-select>

<br />
<small>Selected: {{ selectedAccounts | json }}</small>

Items with already grouped children array

TypeScript
HTML

import { Component, OnInit, ChangeDetectionStrategy } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { JsonPipe } from '@angular/common';
import { NgOptgroupTemplateDirective, NgOptionTemplateDirective, NgSelectComponent } from '@ng-select/ng-select';

@Component({
    selector: 'ng-group-children-example',
    templateUrl: './group-children-example.component.html',
    styleUrls: ['./group-children-example.component.scss'],
    changeDetection: ChangeDetectionStrategy.Eager,
    imports: [NgSelectComponent, FormsModule, NgOptgroupTemplateDirective, NgOptionTemplateDirective, JsonPipe],
})
export class GroupChildrenExampleComponent implements OnInit {
    selectedProjects = [];
    projects = [
        {
            id: 'p1',
            title: 'Project A',
            subprojects: [
                { title: 'Subproject 1 of A', id: 's1p1' },
                { title: 'Subproject 2 of A', id: 's2p1' },
            ],
        },
        {
            id: 'p2',
            title: 'Project B',
            subprojects: [
                { title: 'Subproject 1 of B', id: 's1p2' },
                { title: 'Subproject 2 of B', id: 's2p2' },
            ],
        },
    ];

    constructor() {}

    ngOnInit() {}
}

<p>Group by children array. Note that when grouping by already grouped items ng-optgroup-tmp is required to display correct headers.</p>

<ng-select [items]="projects" bindLabel="title" bindValue="id" groupBy="subprojects" [multiple]="true" [(ngModel)]="selectedProjects">
    <ng-template ng-optgroup-tmp let-item="item">
        {{ item.title }}
    </ng-template>
    <ng-template ng-option-tmp let-item="item">
        {{ item.title }}
    </ng-template>
</ng-select>

<br />
<small>Selected: {{ selectedProjects | json }}</small>

API

Inputs used by the examples on this page:

Input	Type	Default	Description
[groupBy]	`string` \| `Function`	null	Allow to group items by key or function expression
[groupValue]	`(groupKey: string, children: any[]) => Object`	-	Function expression to provide group value
[selectableGroup]	`boolean`	false	Allow to select group when groupBy is used
[selectableGroupAsModel]	`boolean`	true	Indicates whether to select all children or group itself
[hideSelected]	`boolean`	`false`	Allows to hide selected items.
[items]	`Array<any>`	`[]`	Items array
[multiple]	`boolean`	`false`	Allows to select multiple items.
[closeOnSelect]	`boolean`	true	Whether to close the menu when a value is selected
[compareWith]	`(a: any, b: any) => boolean`	`(a, b) => a === b`	A function to compare the option values with the selected values. The first argument is a value from an option. The second is a value from the selection(model). A boolean should be returned.
bindLabel	`string`	`label`	Object property to use for label. Default `label`
bindValue	`string`	`-`	Object property to use for selected model. By default binds to whole object.

See the NgSelectComponent API reference for the complete list of inputs and outputs.