feat(table): add the ability to show a data row when no data is available

As the table is set up at the moment, there's no convenient way to show the user something when their filtered table didn't match any data. These changes add a new directive that renders out a single row when no other data is available which can be used to show a message.

Author: crisbeto

src/cdk/table/row.ts

@@ -294,3 +294,11 @@ export class CdkFooterRow {
 })
 export class CdkRow {
 }
+
+/** Row that can be used to display a message when no data is shown in the table. */
+@Directive({
+  selector: 'ng-template[cdkEmptyPlaceholderRowDef]'
+})
+export class CdkEmptyPlaceholderRowDef {
+  constructor(public templateRef: TemplateRef<unknown>) {}
+}

src/cdk/table/table-module.ts

@@ -7,10 +7,17 @@
  */
 
 import {NgModule} from '@angular/core';
-import {HeaderRowOutlet, DataRowOutlet, CdkTable, FooterRowOutlet} from './table';
+import {
+  HeaderRowOutlet,
+  DataRowOutlet,
+  CdkTable,
+  FooterRowOutlet,
+  EmptyPlaceholderRowOutlet,
+} from './table';
 import {
   CdkCellOutlet, CdkFooterRow, CdkFooterRowDef, CdkHeaderRow, CdkHeaderRowDef, CdkRow,
-  CdkRowDef
+  CdkRowDef,
+  CdkEmptyPlaceholderRowDef
 } from './row';
 import {
   CdkColumnDef, CdkHeaderCellDef, CdkHeaderCell, CdkCell, CdkCellDef,
@@ -38,6 +45,8 @@ const EXPORTED_DECLARATIONS = [
   HeaderRowOutlet,
   FooterRowOutlet,
   CdkTextColumn,
+  CdkEmptyPlaceholderRowDef,
+  EmptyPlaceholderRowOutlet,
 ];
 
 @NgModule({

src/cdk/table/table.spec.ts

@@ -285,6 +285,22 @@ describe('CdkTable', () => {
         ['Footer C', 'Footer B'],
       ]);
     });
+
+    it('should be able to show a message when no data is being displayed', () => {
+      expect(tableElement.textContent!.trim()).not.toContain('No data');
+
+      const originalData = dataSource.data;
+      dataSource.data = [];
+      fixture.detectChanges();
+
+      expect(tableElement.textContent!.trim()).toContain('No data');
+
+      dataSource.data = originalData;
+      fixture.detectChanges();
+
+      expect(tableElement.textContent!.trim()).not.toContain('No data');
+    });
+
   });
 
   it('should render no rows when the data is null', fakeAsync(() => {
@@ -482,6 +498,28 @@ describe('CdkTable', () => {
     ]);
   });
 
+  it('should be able to show a message when no data is being displayed in a native table', () => {
+    const thisFixture = createComponent(NativeHtmlTableApp);
+    thisFixture.detectChanges();
+
+    // Assert that the data is inside the tbody specifically.
+    const tbody = thisFixture.nativeElement.querySelector('tbody');
+    const dataSource = thisFixture.componentInstance.dataSource!;
+    const originalData = dataSource.data;
+
+    expect(tbody.textContent!.trim()).not.toContain('No data');
+
+    dataSource.data = [];
+    thisFixture.detectChanges();
+
+    expect(tbody.textContent!.trim()).toContain('No data');
+
+    dataSource.data = originalData;
+    thisFixture.detectChanges();
+
+    expect(tbody.textContent!.trim()).not.toContain('No data');
+  });
+
   it('should apply correct roles for native table elements', () => {
     const thisFixture = createComponent(NativeHtmlTableApp);
     const thisTableElement: HTMLTableElement = thisFixture.nativeElement.querySelector('table');
@@ -1459,6 +1497,8 @@ class BooleanDataSource extends DataSource<boolean> {
                *cdkRowDef="let row; columns: columnsToRender"></cdk-row>
       <cdk-footer-row class="customFooterRowClass"
                       *cdkFooterRowDef="columnsToRender"></cdk-footer-row>
+
+      <div *cdkEmptyPlaceholderRowDef>No data</div>
     </cdk-table>
   `
 })
@@ -2266,6 +2306,9 @@ class OuterTableApp {
 
       <tr cdk-header-row *cdkHeaderRowDef="columnsToRender"></tr>
       <tr cdk-row *cdkRowDef="let row; columns: columnsToRender" class="customRowClass"></tr>
+      <tr *cdkEmptyPlaceholderRowDef>
+        <td>No data</td>
+      </tr>
     </table>
   `
 })

src/cdk/table/table.ts

@@ -35,7 +35,8 @@ import {
   TrackByFunction,
   ViewChild,
   ViewContainerRef,
-  ViewEncapsulation
+  ViewEncapsulation,
+  ContentChild
 } from '@angular/core';
 import {
   BehaviorSubject,
@@ -54,7 +55,8 @@ import {
   CdkCellOutletRowContext,
   CdkFooterRowDef,
   CdkHeaderRowDef,
-  CdkRowDef
+  CdkRowDef,
+  CdkEmptyPlaceholderRowDef
 } from './row';
 import {StickyStyler} from './sticky-styler';
 import {
@@ -105,6 +107,16 @@ export class FooterRowOutlet implements RowOutlet {
   constructor(public viewContainer: ViewContainerRef, public elementRef: ElementRef) {}
 }
 
+/**
+ * Provides a handle for the table to grab the view
+ * container's ng-container to insert the placeholder row.
+ * @docs-private
+ */
+@Directive({selector: '[emptyPlaceholderRowOutlet]'})
+export class EmptyPlaceholderRowOutlet implements RowOutlet {
+  constructor(public viewContainer: ViewContainerRef, public elementRef: ElementRef) {}
+}
+
 /**
  * The table template that can be used by the mat-table. Should not be used outside of the
  * material library.
@@ -117,6 +129,7 @@ export const CDK_TABLE_TEMPLATE =
   <ng-content select="caption"></ng-content>
   <ng-container headerRowOutlet></ng-container>
   <ng-container rowOutlet></ng-container>
+  <ng-container emptyPlaceholderRowOutlet></ng-container>
   <ng-container footerRowOutlet></ng-container>
 `;
 
@@ -290,6 +303,9 @@ export class CdkTable<T> implements AfterContentChecked, CollectionViewer, OnDes
    */
   protected stickyCssClass: string = 'cdk-table-sticky';
 
+  /** Whether the placeholder row is currently showing anything. */
+  private _isShowingEmptyPlaceholderRow = false;
+
   /**
    * Tracking function that will be used to check the differences in data changes. Used similarly
    * to `ngFor` `trackBy` function. Optimize row operations by identifying a row based on its data
@@ -376,6 +392,8 @@ export class CdkTable<T> implements AfterContentChecked, CollectionViewer, OnDes
   @ViewChild(DataRowOutlet, {static: true}) _rowOutlet: DataRowOutlet;
   @ViewChild(HeaderRowOutlet, {static: true}) _headerRowOutlet: HeaderRowOutlet;
   @ViewChild(FooterRowOutlet, {static: true}) _footerRowOutlet: FooterRowOutlet;
+  @ViewChild(EmptyPlaceholderRowOutlet, {static: true})
+  _emptyPlaceholderRowOutlet: EmptyPlaceholderRowOutlet;
 
   /**
    * The column definitions provided by the user that contain what the header, data, and footer
@@ -396,6 +414,9 @@ export class CdkTable<T> implements AfterContentChecked, CollectionViewer, OnDes
     descendants: true
   }) _contentFooterRowDefs: QueryList<CdkFooterRowDef>;
 
+  /** Row definition that will only be rendered if there's no data in the table. */
+  @ContentChild(CdkEmptyPlaceholderRowDef) _emptyPlaceholderRowDef: CdkEmptyPlaceholderRowDef;
+
   constructor(
       protected readonly _differs: IterableDiffers,
       protected readonly _changeDetectorRef: ChangeDetectorRef,
@@ -461,6 +482,7 @@ export class CdkTable<T> implements AfterContentChecked, CollectionViewer, OnDes
 
   ngOnDestroy() {
     this._rowOutlet.viewContainer.clear();
+    this._emptyPlaceholderRowOutlet.viewContainer.clear();
     this._headerRowOutlet.viewContainer.clear();
     this._footerRowOutlet.viewContainer.clear();
 
@@ -516,6 +538,7 @@ export class CdkTable<T> implements AfterContentChecked, CollectionViewer, OnDes
       rowView.context.$implicit = record.item.data;
     });
 
+    this._updateEmptyPlaceholderRow();
     this.updateStickyColumnStyles();
   }
 
@@ -1012,15 +1035,19 @@ export class CdkTable<T> implements AfterContentChecked, CollectionViewer, OnDes
   private _applyNativeTableSections() {
     const documentFragment = this._document.createDocumentFragment();
     const sections = [
-      {tag: 'thead', outlet: this._headerRowOutlet},
-      {tag: 'tbody', outlet: this._rowOutlet},
-      {tag: 'tfoot', outlet: this._footerRowOutlet},
+      {tag: 'thead', outlets: [this._headerRowOutlet]},
+      {tag: 'tbody', outlets: [this._rowOutlet, this._emptyPlaceholderRowOutlet]},
+      {tag: 'tfoot', outlets: [this._footerRowOutlet]},
     ];
 
     for (const section of sections) {
       const element = this._document.createElement(section.tag);
       element.setAttribute('role', 'rowgroup');
-      element.appendChild(section.outlet.elementRef.nativeElement);
+
+      for (const outlet of section.outlets) {
+        element.appendChild(outlet.elementRef.nativeElement);
+      }
+
       documentFragment.appendChild(element);
     }
 
@@ -1084,6 +1111,25 @@ export class CdkTable<T> implements AfterContentChecked, CollectionViewer, OnDes
         });
   }
 
+  /** Creates or removes the empty placeholder row, depending on whether any data is being shown. */
+  private _updateEmptyPlaceholderRow() {
+    if (this._emptyPlaceholderRowDef) {
+      const shouldShow = this._rowOutlet.viewContainer.length === 0;
+
+      if (shouldShow !== this._isShowingEmptyPlaceholderRow) {
+        const container = this._emptyPlaceholderRowOutlet.viewContainer;
+
+        if (shouldShow) {
+          container.createEmbeddedView(this._emptyPlaceholderRowDef.templateRef);
+        } else {
+          container.clear();
+        }
+
+        this._isShowingEmptyPlaceholderRow = shouldShow;
+      }
+    }
+  }
+
   static ngAcceptInputType_multiTemplateDataRows: BooleanInput;
 }
 

src/components-examples/material/table/table-filtering/table-filtering-example.html

@@ -1,6 +1,6 @@
 <mat-form-field>
   <mat-label>Filter</mat-label>
-  <input matInput (keyup)="applyFilter($event)" placeholder="Ex. ium">
+  <input matInput (keyup)="applyFilter($event)" placeholder="Ex. ium" #input>
 </mat-form-field>
 
 <table mat-table [dataSource]="dataSource" class="mat-elevation-z8">
@@ -31,4 +31,9 @@
 
   <tr mat-header-row *matHeaderRowDef="displayedColumns"></tr>
   <tr mat-row *matRowDef="let row; columns: displayedColumns;"></tr>
+
+  <!-- Row shown when there is no matching data. -->
+  <tr class="mat-row" *matEmptyPlaceholderRowDef>
+    <td class="mat-cell" colspan="4">No data matching the filter "{{input.value}}"</td>
+  </tr>
 </table>

src/components-examples/material/table/table-overview/table-overview-example.html

@@ -1,6 +1,6 @@
 <mat-form-field>
   <mat-label>Filter</mat-label>
-  <input matInput (keyup)="applyFilter($event)" placeholder="Ex. Mia">
+  <input matInput (keyup)="applyFilter($event)" placeholder="Ex. Mia" #input>
 </mat-form-field>
 
 <div class="mat-elevation-z8">
@@ -31,7 +31,11 @@
     </ng-container>
 
     <tr mat-header-row *matHeaderRowDef="displayedColumns"></tr>
-    <tr mat-row *matRowDef="let row; columns: displayedColumns;">
+    <tr mat-row *matRowDef="let row; columns: displayedColumns;"></tr>
+
+    <!-- Row shown when there is no matching data. -->
+    <tr class="mat-row" *matEmptyPlaceholderRowDef>
+      <td class="mat-cell" colspan="4">No data matching the filter "{{input.value}}"</td>
     </tr>
   </table>
 

src/material-experimental/mdc-table/module.ts

@@ -25,7 +25,8 @@ import {
   MatHeaderRow,
   MatHeaderRowDef,
   MatRow,
-  MatRowDef
+  MatRowDef,
+  MatEmptyPlaceholderRowDef
 } from './row';
 
 const EXPORTED_DECLARATIONS = [
@@ -50,6 +51,7 @@ const EXPORTED_DECLARATIONS = [
   MatHeaderRow,
   MatRow,
   MatFooterRow,
+  MatEmptyPlaceholderRowDef,
 ];
 
 @NgModule({

src/material-experimental/mdc-table/row.ts

@@ -14,7 +14,8 @@ import {
   CdkHeaderRow,
   CdkHeaderRowDef,
   CdkRow,
-  CdkRowDef
+  CdkRowDef,
+  CdkEmptyPlaceholderRowDef
 } from '@angular/cdk/table';
 import {ChangeDetectionStrategy, Component, Directive, ViewEncapsulation} from '@angular/core';
 
@@ -110,3 +111,11 @@ export class MatFooterRow extends CdkFooterRow {
 })
 export class MatRow extends CdkRow {
 }
+
+/** Row that can be used to display a message when no data is shown in the table. */
+@Directive({
+  selector: 'ng-template[matEmptyPlaceholderRowDef]',
+  providers: [{provide: CdkEmptyPlaceholderRowDef, useExisting: MatEmptyPlaceholderRowDef}],
+})
+export class MatEmptyPlaceholderRowDef extends CdkEmptyPlaceholderRowDef {
+}

src/material-experimental/mdc-table/table.spec.ts

@@ -79,6 +79,28 @@ describe('MDC-based MatTable', () => {
         ['Footer A'],
       ]);
     });
+
+    it('should be able to show a message when no data is being displayed', () => {
+      const fixture = TestBed.createComponent(MatTableApp);
+      fixture.detectChanges();
+
+      // Assert that the data is inside the tbody specifically.
+      const tbody = fixture.nativeElement.querySelector('tbody')!;
+      const initialData = fixture.componentInstance.dataSource!.data;
+
+      expect(tbody.textContent.trim()).not.toContain('No data');
+
+      fixture.componentInstance.dataSource!.data = [];
+      fixture.detectChanges();
+
+      expect(tbody.textContent.trim()).toContain('No data');
+
+      fixture.componentInstance.dataSource!.data = initialData;
+      fixture.detectChanges();
+
+      expect(tbody.textContent.trim()).not.toContain('No data');
+    });
+
   });
 
   it('should render with MatTableDataSource and sort', () => {
@@ -538,6 +560,9 @@ class FakeDataSource extends DataSource<TestData> {
       <tr mat-header-row *matHeaderRowDef="columnsToRender"></tr>
       <tr mat-row *matRowDef="let row; columns: columnsToRender"></tr>
       <tr mat-row *matRowDef="let row; columns: ['special_column']; when: isFourthRow"></tr>
+      <tr *matEmptyPlaceholderRowDef>
+        <td>No data</td>
+      </tr>
       <tr mat-footer-row *matFooterRowDef="columnsToRender"></tr>
     </table>
   `

src/material/table/row.ts

@@ -14,7 +14,8 @@ import {
   CdkHeaderRow,
   CdkHeaderRowDef,
   CdkRow,
-  CdkRowDef
+  CdkRowDef,
+  CdkEmptyPlaceholderRowDef
 } from '@angular/cdk/table';
 import {ChangeDetectionStrategy, Component, Directive, ViewEncapsulation} from '@angular/core';
 
@@ -110,3 +111,11 @@ export class MatFooterRow extends CdkFooterRow {
 })
 export class MatRow extends CdkRow {
 }
+
+/** Row that can be used to display a message when no data is shown in the table. */
+@Directive({
+  selector: 'ng-template[matEmptyPlaceholderRowDef]',
+  providers: [{provide: CdkEmptyPlaceholderRowDef, useExisting: MatEmptyPlaceholderRowDef}],
+})
+export class MatEmptyPlaceholderRowDef extends CdkEmptyPlaceholderRowDef {
+}