ng-hub-ui-paginable

✨ Inspiration

This library arises from the need to offer highly configurable, accessible, and modern data visualization components for Angular applications, enabling integrated lists, tables, and pagination with full support for signals, reactive forms, and complete render customization.

🧩 Library Family ng-hub-ui

ng-hub-ui-paginable is part of the ng-hub-ui ecosystem, a family of modern Angular components focused on user experience, productivity, and compatibility with Angular Signals. Each package solves a specific interface problem without overloading business logic.

📦 Description

ng-hub-ui-paginable provides a table (<hub-ui-table>), a list (<hub-ui-list>), and a paginator (<hub-ui-paginator>) ready to work together or separately, making it easy to manage paginated data, searches, filters, and item selection.

In this first version of the README, we will focus on the Table component.

🎯 Features

• Full support for Angular Signals (model(), input(), computed(), effect()).
• Compatibility with separate or grouped inputs via PaginationState.
• Local search and column filters (text, range, boolean, etc.).
• Ascending/descending column sorting.
• Single or multiple row selection.
• Expandable rows.
• Local or remote pagination.
• Support for custom templates (headers, cells, filters, empty, errors, etc.).
• Responsive layout configurable by breakpoint.

🚀 Installation

npm install ng-hub-ui-paginable

🎨 Styling

Make sure to include the global base styles (SCSS):

@use 'ng-hub-ui-paginable/src/lib/styles/base.scss';

If you use Angular CLI, you can add it in angular.json as a stylePreprocessorIncludePaths.

⚙️ Usage

<hub-ui-table
  [headers]="headers"
  [data]="data.value()"
  [(page)]="page"
  [totalItems]="totalItems"
  [loading]="loading"
  [searchable]="true"
  [selectable]="true"
  [multiple]="true"
  [(searchTerm)]="searchTerm"
  [(ordination)]="ordination"
></hub-ui-table>

🪄 Inputs

📤 Outputs

The component implements ControlValueAccessor, so you can use [(ngModel)] or use it with formControl.

You can also capture row clicks:

@clickFn="onItemClick($event)"

Where $event includes: item, depth, index, selected, collapsed.

The hub-ui-table component allows you to override almost any visual section using Angular templates (<ng-template>). This allows you to adapt the visualization of each cell, header, or special content to your specific needs.

🔠 headerTpt (column header)

Allows replacing the content of a specific header.

<ng-template headerTpt header="name">
  <span class="text-primary fw-bold">Full Name</span>
</ng-template>

<ng-template headerTpt header="birthday">
  <i class="fa-solid fa-cake-candles me-2"></i> Date of Birth
</ng-template>

📄 cellTpt (column cell)

Overrides the visualization of a specific cell.

<ng-template cellTpt header="name" let-data="data">
  {{ data.name.toUpperCase() }}
</ng-template>

<ng-template cellTpt header="age" let-data="data">
  <span [class.text-success]="data.age >= 18"> {{ data.age }} years </span>
</ng-template>

<ng-template cellTpt header="adult" let-data="data">
  <hub-ui-icon
    [config]="{ type: 'material', value: data.adult ? 'check' : 'close' }"
  ></hub-ui-icon>
</ng-template>

🚫 notFoundTpt (empty state)

Displays custom content when there is no data to show.

<ng-template notFoundTpt>
  <div class="alert alert-info text-center">
    <i class="fa-solid fa-circle-info me-2"></i>
    No results found for your search.
  </div>
</ng-template>

⏳ loadingTpt (loading state)

Renders content while loading is true.

<ng-template loadingTpt>
  <div class="text-center p-4">
    <div class="spinner-border text-primary" role="status"></div>
    <p>Loading data, please wait...</p>
  </div>
</ng-template>

❌ errorTpt (error state)

Displayed if there is an error template configured and it is manually triggered from the component.

<ng-template errorTpt>
  <div class="alert alert-danger text-center">
    <i class="fa-solid fa-triangle-exclamation me-2"></i>
    An unexpected error has occurred. Try reloading the table.
  </div>
</ng-template>

📂 rowTpt (custom row)

Allows you to completely redefine the structure of a row. Useful when the table is not used as a <table> but as a <div>, or if you need a "card"-type display.

<ng-template tableRow let-item>
  <tr>
    <td>{{ item.name }}</td>
    <td>{{ item.lastname }}</td>
    <td>{{ item.age }} years</td>
  </tr>
</ng-template>

You can also use tableRowTpt with expandable components.

🔍 Custom filters (filterTpt)

You can customize the column filter interface using individual templates per header.

<ng-template filterTpt header="birthday" let-formControl="formControl">
  <input
    type="date"
    class="form-control"
    [formControl]="formControl"
    placeholder="Filter by date"
  />
</ng-template>

<ng-template filterTpt header="age" let-formControl="formControl">
  <div class="d-flex gap-2">
    <input
      type="number"
      class="form-control"
      [formControl]="formControl.controls.start"
      placeholder="Min."
    />
    <input
      type="number"
      class="form-control"
      [formControl]="formControl.controls.end"
      placeholder="Max."
    />
  </div>
</ng-template>

<ng-template filterTpt header="adult" let-formControl="formControl">
  <select class="form-select" [formControl]="formControl">
    <option [ngValue]="null">All</option>
    <option [ngValue]="true">Yes</option>
    <option [ngValue]="false">No</option>
  </select>
</ng-template>

This allows you to adapt any type of visual filter (date-range, boolean, dropdown, etc.) without losing reactivity.

🧠 Pagination and Data Handling

The hub-ui-table component can receive data in two different ways:

1. Grouped form (PaginationState<T>)

Ideal if you manage pagination outside the component. The data input can directly accept an object with the full pagination structure:

<hub-ui-table
  [data]="{
    page: page(),
    perPage: perPage(),
    totalItems: totalItems(),
    data: data()
  }"
></hub-ui-table>

This form is useful when you manage PaginationState in a single place (for example, from a service, computed(), or store).

2. Split form (individual inputs)

You can also pass each value separately:

<hub-ui-table
  [data]="data()"
  [page]="page()"
  [perPage]="perPage()"
  [totalItems]="totalItems()"
></hub-ui-table>

It is important that if you choose this form, all inputs are present. If page, perPage, or totalItems are missing, the component will show an error in the console.

Both forms are compatible with Signals and can be easily integrated with model() and computed().

🧬 Interface PaginationState<T>

export interface PaginationState<T = any> {
  page: number | null;
  perPage: number | null;
  totalItems: number | null;
  data: ReadonlyArray<T> | null;
}

🤝 Contribution

All contributions are welcome! You can open issues, send pull requests, or propose feature improvements.

git clone https://github.com/carlos-morcillo/ng-hub-ui-paginable.git

☕ Support

Do you like this library? You can support us by buying us a coffee ☕:

📄 License

MIT © ng-hub-ui contributors