List View

The Ignite UI for Angular List component displays rows of items and supports one or more header items as well as search and filtering of list items. Each list item is completely templateable and will support any valid HTML or Angular component.

List Demo

Usage

At its core the list component allows you to easily display a vertical list of items. The default styling of the items is done according to the single-line list specification as per the Material Design guidelines. To get started with the Ignite UI for Angular List, let's first import the IgxListModule in our app.module.ts file:

// app.module.ts

...
import { IgxListModule } from 'igniteui-angular';

@NgModule({
    ...
    imports: [..., IgxListModule],
    ...
})
export class AppModule {}

Then in the template of our contacts component we can create our list, but what if currently (or at some point in the future) we have no items in it? In this case, the list provides us with a default template that is used when the list is empty. We can always provide our own template for the look of our empty list by simply using the igxEmptyList directive. In this case, the default template will not be used:

<!--contacts.component.html-->

<igx-list>
    <ng-template igxEmptyList>
        <p class="empty">No contacts! :(</p>
    </ng-template>
</igx-list>

And our style for the empty template:

/* contacts.component.css */

.empty {
    color: rgba(0, 153, 255, 1);
    font-size: 25px;
    font-weight: 600;
    text-shadow: 2px 1px 2px rgba(150, 150, 150, 1);
}

If all went great, this is how our empty list should look like:

Sometimes there may be a delay in your data loading. In this case you can set the list's isLoading property to true and a default template will inform the user regarding the ongoing data loading process. You can also provide your own loading template using the igxDataLoading directive:

<!--contacts.component.html-->

<igx-list>
    <ng-template igxDataLoading>
        <p class="loading">Patience, we are currently loading your data...</p>
    </ng-template>
</igx-list>
/* contacts.component.css */

.loading {
    color: rgba(255, 153, 0, 1);
    font-size: 25px;
    font-weight: 600;
    text-shadow: 2px 1px 2px rgba(150, 150, 150, 1);
}

Add List Items

It's nice having a template for when the list is empty, but now let's add some items! We can add the following code to get a simple list of items:

<!--contacts.component.html-->

<igx-list>
    <igx-list-item isHeader="true">Header</igx-list-item>
    <igx-list-item>Item 1</igx-list-item>
    <igx-list-item>Item 2</igx-list-item>
    <igx-list-item>Item 3</igx-list-item>
</igx-list>

If all went well, you should see the following in your browser:

Custom List Items

Let's up our game a bit and create some custom markup and styles for our list items. Say we want to create a list of contacts with a name and a phone number displayed under the name. In our component typescript file we can define a list of contacts:

// contacts.component.ts
...
public contacts = [{
    name: "Terrance Orta",
    phone: "770-504-2217"
}, {
    name: "Richard Mahoney",
    phone: "423-676-2869"
}, {
    name: "Donna Price",
    phone: "859-496-2817"
}, {
    name: "Lisa Landers",
    phone: "901-747-3428"
}, {
    name: "Dorothy H. Spencer",
    phone: "573-394-9254"
}];

Now that we have some data we want to render, let's set up some markup:

<!--contacts.component.html-->

<igx-list>
  <igx-list-item isHeader="true">
    Contacts
  </igx-list-item>
  <igx-list-item *ngFor="let contact of contacts">
    <span class="name">{{ contact.name }}</span>
    <span class="phone">{{ contact.phone }}</span>
  </igx-list-item>
</igx-list>
Note

The list item uses flex as its display value, with flex-direction set to column. Bear this in mind when building list layouts.

You may have noticed that despite the fact that we used span elements to display the name and phone number for our contacts, we still see them rendered one under the other. This is due to the column nature of each list item. Now that we have that out of the way, let's add some custom styling. We added two new classes to our name and phone spans - name and phone. Let's use those classes to style the items:

/* contacts.component.css */

.name {
    font-weight: 600;
}

.phone {
    font-size: 0.875em;
}

After all that our list should now look like that:

Adding Avatar and Icons

We can use some of our other components in conjunction with the IgxList component to enrich the experience and add some functionality. We can have a nice picture avatar to the left of the name and phone values. Additionally, we can add a star icon to the right of them to allow the user to favorite a contact. To do that let's grab the IgxAvatar and IgxIcon modules and import them in our app.module.ts file.

// app.module.ts

...
import {
    IgxListModule,
    IgxAvatarModule,
    IgxIconModule
} from 'igniteui-angular';

@NgModule({
    ...
    imports: [..., IgxAvatarModule, IgxIconModule],
})
export class AppModule {}

Next, we need to add some more information to our contact object, like a photo source for our avatar and a isFavorite property to indicate the contact's favorite status.

// contacts.comoponent.ts

public contacts = [{
    name: 'Terrance Orta',
    phone: '770-504-2217',
    photo: 'https://randomuser.me/api/portraits/men/27.jpg',
    isFavorite: false
}, {
    name: 'Richard Mahoney',
    phone: '423-676-2869',
    photo: 'https://randomuser.me/api/portraits/men/1.jpg',
    isFavorite: true
}, {
    name: 'Donna Price',
    phone: '859-496-2817',
    photo: 'https://randomuser.me/api/portraits/women/50.jpg',
    isFavorite: false
}, {
    name: 'Lisa Landers',
    phone: '901-747-3428',
    photo: 'https://randomuser.me/api/portraits/women/3.jpg',
    isFavorite: false
}, {
    name: 'Dorothy H. Spencer',
    phone: '573-394-9254',
    photo: 'https://randomuser.me/api/portraits/women/67.jpg',
    isFavorite: true
}];

Cool, now let's update the template for our contacts list to to show the avatar and icon:

<!--contacts.component.html-->

<igx-list>
  <igx-list-item isHeader="true">
    Contacts
  </igx-list-item>
  <igx-list-item #item *ngFor="let contact of contacts;">
    <div class="item-container">
      <div class="contact">
        <igx-avatar [src]="contact.photo" roundShape="true"></igx-avatar>
        <div class="contact__info">
          <span class="name">{{ contact.name }}</span>
          <span class="phone">{{ contact.phone }}</span>
        </div>
      </div>
      <igx-icon name="star" [color]="contact.isFavorite ? 'orange' : 'lightgray'" (click)="toggleFavorite(item)"></igx-icon>
    </div>
  </igx-list-item>
</igx-list>

First we wrap all our elements in an item container to allow us to style the flow a bit easier. Then we add our IgxAvatar component alongside our contact info in a contact wrapper. Lastly, we include the IgxIcon component. Let's update the css stylesheet to reflect the changes made to our markup:

/* contacts.component.css */

igx-icon {
    cursor: pointer;
    user-select: none;
}

.item-container {
    display: flex;
    justify-content: space-between;
    align-items: center;
}

.contact {
    display: flex;
    flex: 1 0 240px;
    align-items: center;
}

.contact__info {
    display: flex;
    flex-flow: column nowrap;
    margin-left: 24px;
}

.name {
    font-weight: 600;
}

.phone {
    font-size: 0.875em;
}

We then listen for a click event on the IgxIcon component to toggle the isFavorite property in our contact object.

// contacts.component.ts

...
toggleFavorite(item: IgxListItem) {
    const contact = this.contacts[item.index - 1];
    contact.isFavorite = !contact.isFavorite;
}

And here's the result of all that work:

Filtering

Our list is looking good, but wouldn't it be even better if we could search for contacts by name? We can easily achieve that by using our filtering pipe. Let's do this.

Let's add an input field to the top in our component template first and bind it to a property in our component called searchContact:

<!--contacts.component.html-->

<igx-input-group type="search" class="search">
    <igx-prefix>
        <igx-icon>search</igx-icon>
    </igx-prefix>
    <input #search igxInput placeholder="Search Contacts" [(ngModel)]="searchContact">
    <igx-suffix *ngIf="search.value.length > 0" (click)="searchContact = null">
        <igx-icon>clear</igx-icon>
    </igx-suffix>
</igx-input-group>

It's time to import the IgxFilterModule and the IgxInputGroupModule in our app.module.ts file and IgxFilterOptions in our contacts component:

    // app.module.ts
    ...
    import { IgxFilterModule, IgxInputGroupModule } from 'igniteui-angular';

    @NgModule({
        imports: [..., IgxFilterModule, IgxInputGroupModule]
    })

    // contacts.component.ts
    ...
    import { IgxFilterOptions } from 'igniteui-angular';

    @Component({...})
    export class ContactListComponent {
        public searchContact: string;
        ...
        get filterContacts(): IgxFilterOptions {
            const fo = new IgxFilterOptions();
            fo.key = 'name';
            fo.inputValue = this.searchContact;
            return fo;
        }
    }

After importing the IgxFilterOptions, we need to register a new getter method that will return the filtering options to be used by the pipe each time the searchContact property gets updated. For the filter to work we need to register a key to filter the contact object by. In our case that would be the name of each contact. The second property that has to be registered on the IgxFilterOptions object is the value that we should check against when comparing our contact name. This would be the searchContact property that we bound to the input field above our contacts list.

Finally, we need to apply the filtering pipe to our contacts data before we can use it. So in our template we simply add:

<!--contacts.component.html-->

<igx-list-item *ngFor="let contact of contacts | igxFilter: filterContacts; let i = index">
    ...
</igx-list-item>

API Summary

In this article we covered a lot of ground with the list component. We created a list of contact items. Used some additional Ignite UI for Angular components inside our list items, like avatars and icons. Created some custom item layout and styled it. Finally, we added list filtering. The list component has a few more APIs to explore, which are listed below.

Inputs

The following inputs are available on the igx-list component:

Name Type Description
allowLeftPanning Boolean Determines whether the left panning of an item is allowed.
allowRightPanning Boolean Determines whether the right panning of an item is allowed.
isLoading Boolean If true the loading template will be used, if false the empty list template will be used.
dataLoadingTemplate IgxDataLoadingTemplateDirective The custom template to be used when the list is empty and isLoading is true.
emptyListTemplate IgxEmptyListTemplateDirective The custom template to be used when the list is empty and isLoading is false.

The following inputs are available on the igx-list-item component:

Name Type Description
isHeader Boolean Sets the current list item as list header.
hidden Boolean Determines whether the item should be displayed.

Outputs

The following outputs are available on the igx-list component:

Name Type Description
onPanStateChange EventEmitter Emits an event with the current list when pan gesture is executed on list item.
onLeftPan EventEmitter Emits an event with the current list when left pan gesture is executed on list item.
onRightPan EventEmitter Emits an event with the current list when right pan gesture is executed on list item.
onItemClicked EventEmitter Emits an event with the current list when a list item has been clicked.

Properties

The following properties are available on the igx-list component:

Name Type Description
children QueryList Returns a collection of all IListChild components: items and headers.
items IgxListItemComponent[] Returns an array of all list items excluding item headers.
headers IgxListItemComponent[] Returns an array of all list headers.

The following properties are available on the igx-list-item component:

Name Type Description
index number Retrieve the index of the list item.
panState IgxListPanState Retrieve the pan state of the list item.
list IgxListComponent Retrieve the list that is associated with the list item.

Additional Resources

Our community is active and always welcoming to new ideas.