angular-smart-table

Reusable Angular smart table library that supports:

• Client-side mode (local array) — built-in paging, sorting, and filtering.
• Server-side mode (parent calls API) — table emits events for paging, search, and sorting.
• Auto API mode (table calls API) — table performs HTTP calls itself based on configuration.

This project is an Angular library, not an application.

It uses Font Awesome icons for sorting, pagination, and search clear controls.

Installation

npm install angular-smart-table

Add the standalone component to your feature module or standalone route component:

import { SmartTableComponent } from 'angular-smart-table';

Important: For Auto API Mode, you must import HttpClientModule in your app:

import { HttpClientModule } from '@angular/common/http';

@NgModule({
  imports: [HttpClientModule, /* ... */]
})
export class AppModule {}

Or for standalone apps:

import { provideHttpClient } from '@angular/common/http';

bootstrapApplication(AppComponent, {
  providers: [provideHttpClient(), /* ... */]
});

Usage Modes

1. Client-Side Mode (Local Array)

Use when all data is already loaded in the browser. The table handles paging, sorting, and filtering automatically without backend requests.

<app-smart-table
  [data]="users"
  [columns]="columns"
  [actions]="actions"
  [enablePagination]="true">
</app-smart-table>

2. Server-Side Mode (Parent Calls API)

Use when the parent component is responsible for calling the backend. The table emits events describing paging, search, and sorting.

<app-smart-table
  [columns]="columns"
  [data]="users"
  [serverSide]="true"
  [totalRecords]="total"
  [currentSort]="currentSort"
  [page]="currentPage"
  [pageSize]="pageSize"
  (pageChange)="loadUsers($event)"
  (searchChange)="search($event)"
  (sortChange)="sort($event)"
  (actionClick)="handleAction($event)">
</app-smart-table>

Component Example:

import { Component } from '@angular/core';
import { SmartTableComponent, SmartTableSort, SmartTablePageChange } from 'angular-smart-table';

@Component({
  selector: 'app-users',
  standalone: true,
  imports: [SmartTableComponent],
  template: `...`
})
export class UsersComponent {
  users: User[] = [];
  totalRecords = 0;
  currentPage = 1;
  pageSize = 10;
  currentSort: SmartTableSort | null = null;

  loadUsers(event: SmartTablePageChange): void {
    this.currentPage = event.page;
    this.pageSize = event.pageSize;
    // Call your API with page, pageSize, search, sort params
    this.apiService.getUsers(event.page, event.pageSize).subscribe(response => {
      this.users = response.data;
      this.totalRecords = response.total;
    });
  }

  search(searchText: string): void {
    // Call your API with search text
    this.apiService.searchUsers(searchText).subscribe(response => {
      this.users = response.data;
      this.totalRecords = response.total;
    });
  }

  sort(event: SmartTableSort): void {
    this.currentSort = event;
    // Call your API with sort params
    this.apiService.getUsers(this.currentPage, this.pageSize, event).subscribe(response => {
      this.users = response.data;
      this.totalRecords = response.total;
    });
  }
}

3. Auto API Mode (Table Calls API)

Use when you want the table to call the backend itself for paging, search, and sorting. The table automatically makes HTTP requests when users interact with pagination, search, or sorting—no manual API code needed.

<app-smart-table
  [columns]="columns"
  [serverSide]="true"
  [enableAutoLoad]="true"
  apiUrl="/user/list"
  apiMethod="POST"
  [apiParams]="{ status: 'Active' }">
</app-smart-table>

Component Example:

import { Component } from '@angular/core';
import { SmartTableComponent, SmartTableColumn } from 'angular-smart-table';

interface User {
  id: number;
  name: string;
  email: string;
}

@Component({
  selector: 'app-users',
  standalone: true,
  imports: [SmartTableComponent],
  template: `
    <app-smart-table
      [columns]="columns"
      [serverSide]="true"
      [enableAutoLoad]="true"
      apiUrl="/api/users"
      apiMethod="POST"
      [apiParams]="{ status: 'Active' }">
    </app-smart-table>
  `
})
export class UsersComponent {
  columns: SmartTableColumn<User>[] = [
    { id: 'name', field: 'name', header: 'Name', sortable: true },
    { id: 'email', field: 'email', header: 'Email', sortable: true }
  ];
}

API Response Format:

The table automatically detects data in common response formats, or you can configure custom paths:

Auto-Detection (Default): The table automatically looks for data in these common formats:

• { data: [], total: 100 }
• { items: [], count: 100 }
• { results: [], totalCount: 100 }
• Direct array: [...]

Custom Response Mapping:

If your API uses different property names, configure custom paths:

<app-smart-table
  [columns]="columns"
  [serverSide]="true"
  [enableAutoLoad]="true"
  apiUrl="/api/users"
  [apiResponseConfig]="{ dataPath: 'userList', totalPath: 'pagination.total' }">
</app-smart-table>

Examples:

// API Response: { userList: [...], pagination: { total: 100 } }
[apiResponseConfig]="{ dataPath: 'userList', totalPath: 'pagination.total' }"

// API Response: { response: { data: { list: [...] }, count: 100 } }
[apiResponseConfig]="{ dataPath: 'response.data.list', totalPath: 'response.count' }"

// API Response: { users: [...] } (total will use array length)
[apiResponseConfig]="{ dataPath: 'users' }"

// API Response is direct array: [...]
[apiResponseConfig]="{ dataPath: '' }"

Path Syntax:

• Use dot notation for nested paths: "response.data.list"
• Empty string "" treats the entire response as the data array
• If totalPath is not provided, the data array length is used

API Request Parameters:

When Auto API Mode is enabled, the table sends these parameters:

• GET requests: Query parameters (?page=1&pageSize=10&search=...&sortField=...&sortDirection=...)
• POST requests: Request body with the same parameters

Parameters include:

• page - Current page number (1-based)
• pageSize - Number of items per page
• search - Search text (if provided)
• sortField - Column field to sort by (if sorting is active)
• sortDirection - Sort direction (asc or desc)
• Any custom parameters from apiParams

Features:

• ✅ Automatic API calls on page change, search (debounced 300ms), and sort
• ✅ Loading state indicator
• ✅ Error handling and display
• ✅ Initial data load on component mount
• ✅ No manual API code required in your component

Inputs

• data — Local array mode only.
• columns — Defines table headers and sortable fields.
• actions — UI action buttons for rows.
• serverSide — Parent handles API calls.
• enableAutoLoad — Table calls API by itself.
• apiUrl — Endpoint for auto mode.
• apiMethod — HTTP method (GET or POST).
• apiParams — Extra filters sent to backend.
• apiResponseConfig — (Optional) Custom response mapping with dataPath and totalPath for non-standard API structures.
• page, pageSize, pageSizes — Pagination control.
• enablePagination — Toggle pagination UI (pagination appears inside table footer with First, Previous, Page Numbers, Next, and Last icon buttons).
• totalRecords — Total dataset size when using server paging.
• currentSort — (Optional) Current sort state for server-side mode to display sort indicators.

Outputs

• pageChange — Triggered when user changes page.
• searchChange — Debounced text search term.
• sortChange — Column sorting changed.
• actionClick — Triggered when a row action button is clicked.

Development Notes

• Uses Angular v15+ and standalone components.
• Uses ChangeDetectionStrategy.OnPush for performance.
• All public exports go through src/public-api.ts.