Index

• 📄 Description
• 📦 Installation
  • 📋 Prerequisites
  • 📥 Install Pro Table Components
• 💻 Usage
  • 📤 Importing
  • 🔽 Expandable Rows
  • 📚 API
• 🔄 Compatibility
• 🤝 Contributions
• ⚖️ Licensing
• 🏁 Wrapping Up

📄 Description

@proangular/pro-table is a type-safe, Angular abstraction over Angular Material’s table. It’s designed for apps using standalone components, signals, and the new control-flow syntax so you can wire up data grids quickly without giving up control of your data model or rendering.

The component keeps Material’s performance, accessibility, and theming surface, while adding strongly-typed columns, selection, copy-on-click, expandable detail rows, and a clean sorting contract that emits intent instead of mutating data.

Why it’s useful (technical)

• Compile-time guarantees for columns & data
  Columns are declared as TableColumn<T>, where key is tied to your row model T. That prevents typos and drift between your data and headers.

• Sorting as a pure UI signal
  The table does not reorder your data. Instead it emits a TableSortChangeEvent<T> with a typed key and direction; you decide how to sort (or not) in your host component. This keeps business logic out of the view layer and plays well with signals/NgRx/etc.

• Expandable rows that are template-driven
  Provide a TemplateRef per row and the table renders it in a dedicated detail row using multiTemplateDataRows. Expansion is reference-based, so you can attach any context object you like.

• Selection with guardrails
  Built-in single/multi select with a master checkbox, an optional max selectable limit, and an emitted list of selected rows without leaking table internals to the host.

• Great DX for common table chores
  One-line copy-to-clipboard per column (with tooltip and snack-bar feedback), sticky headers, row click events, and cell placeholders for empty values. These affordances reduce the “glue code” you normally write around MatTable.

• Built for Angular 20-21+ patterns
  Uses OnPush change detection, @if/@for/@let in templates, and small reactive streams (BehaviorSubject/ReplaySubject + shareReplay) to keep updates efficient. The example shows signals + effect() integrating cleanly with the component’s inputs.

Features

• Strong typing for both column definitions and row data (TableColumn<T>)
• Opt-in selection with max count and rowSelectChange events
• Click-to-copy per column with tooltip and snackbar feedback
• Sticky header option
• Expandable detail rows via TemplateRef + multiTemplateDataRows with animations
• Sort intent via sortChange events no data mutation, you stay in control
• Works seamlessly with standalone components, signals, and Material’s MatSort/MatTable

📦 Installation

Using Node Package Manager (NPM) in a new terminal window run the following commands to install the required dependencies.

📋 Prerequisites

Angular Material

More information on theming Angular Material: https://material.angular.io/guide/theming

ng add @angular/material

📥 Install Pro Table Components

ng add @proangular/pro-table@latest

or

npm install @proangular/pro-table --save

💻 Usage

📤 Importing

Import the table component to use in your Angular application where used:

+ import { TableComponent } from '@proangular/pro-table';

// For modules
@NgModule({
  ...
  imports: [
+   TableComponent,
    ...
  ],
})

// For standalone components
@Component({
  ...
  imports: [
+   TableComponent,
    ...
  ],
})

// Markup usage
+ <pro-table [columns]="columns" [data]="data" />

🔽 Expandable Rows

<pro-table [columns]="columns()" [data]="rowsWithDetailTemplate()" />

<ng-template #detailTemplate let-data="data">
  <pre>{{ data | json }}</pre>
</ng-template>

Map your data to include a template field typed as TableTemplateReferenceExpandableObject if you want per-row detail. The table uses multiTemplateDataRows and a detail row with expandedDetail to render the template when expanded.

See example table code here, or a live demo.

📚 API

Input Bindings (required):

| Input | Type | Default Value | Description | | --------- | ------------------------------- | ------------- | ------------------------------------------------------ | | columns | ReadonlyArray<TableColumn<T>> | N/A | Table column definitions mapped to keys in the data. | | data | readonly T[] | N/A | Table data array to display. |

Input Bindings (optional):

| Input | Type | Default Value | Description | | ---------------------- | ------------------------- | ---------------------- | ------------------------------------------------------ | | highlightOddRows | boolean | false | Highlight odd rows. | | initialSort | TableSortChangeEvent<T> | N/A | Initial sort configuration. | | maxSelectableRows | number | No limit | Maximum number of selectable rows. | | placeholderEmptyData | string | N/A | Placeholder text when no data is available for a cell. | | placeholderEmptyList | string | No items to display. | Placeholder text when data array is empty. | | placeholderLoading | string | Loading... | Placeholder text when data is loading. | | rowClickEnabled | boolean | false | Enable row click event. | | selectable | boolean | false | Enable row selection. | | stickyHeader | boolean | false | Enable sticky table header. | | trackByFn | function | Default trackBy (id) | Custom trackBy function for rows. |

Event Handling

| Event | Type | Description | | ----------------- | --------------------------------------- | ----------------------------------------------------------- | | rowClick | EventEmitter<T> | Emits if a row is clicked when rowClickEnabled is true. | | rowSelectChange | EventEmitter<readonly T[]> | Emits if a row selection changes when selectable is true. | | sortChange | EventEmitter<TableSortChangeEvent<T>> | Emits when sort changes. |

Table Types

// T = Your row data type (object)

interface TableColumn<T extends object> {
  /** Whether the column data is copyable on click */
  copyable?: boolean;
  /** Whether the column is sortable */
  isSortable?: boolean;
  /** The key of the column in the data source */
  key: NestedKeysOfString<T>;
  /** The label for the column */
  label: string;
  /** Minimum width of the column in pixels */
  minWidthPx?: number;
  /** The sort key for the column (if it differs from the `key`) */
  sortKey?: NestedKeysOfString<T> | string;
}

type SortDirection = 'asc' | 'desc' | '';

interface TableSortChangeEvent<T> {
  /** The direction of the sort, or null if cleared */
  direction: SortDirection | null;
  /** The column key being sorted */
  key: NestedKeysOfString<T> | string | null;
}

type TableTemplateReferenceObject<
  C = unknown, // Context type
  T = unknown, // Template type
> = {
  /** The context object passed to the template */
  context: C;
  /** The template reference to render */
  templateRef: import('@angular/core').TemplateRef<T>;
};

interface TableTemplateReferenceExpandableObject<
  C = unknown, // Context type
  T = unknown, // Template type
> extends TableTemplateReferenceObject<C, T> {
  /** Whether the detail row is expanded */
  isExpanded: boolean;
}

🔄 Compatibility

| Angular version | @proangular/pro-table | Install | | --------------- | --------------------- | -------------------------------- | | v21 | v21.x.x | ng add @proangular/pro-table@^21 | | v20 | v20.x.x | ng add @proangular/pro-table@^20 | | v19 | ------ | Untested | | v18 | ------ | Untested | | v17 | ------ | Untested |

🤝 Contributions

Please submit all issues, and feature requests here: https://github.com/ProAngular/pro-table/issues

Contribution:

1. Clone the repo and create a new branch:

• git clone https://github.com/ProAngular/pro-table.git
• git checkout -b username/feature-or-bug-description

2. Bump up the version of package in package.json and package-lock.json, commit all changes, push.

• git add -A
• git commit -m "My commit message"
• git push origin username/feature-or-bug-description

3. Submit code in published PR for review and approval. Add a good description and link any possible user stories or bugs.

• Create a new pull request.

4. Allow CI actions to completely run and verify files.
5. Add/ping reviewers and await approval.

Thank you for any and all contributions!

⚖️ Licensing

This project is licensed under the MIT License. See the LICENSE file for the pertaining license text.

SPDX-License-Identifier: MIT

🏁 Wrapping Up

Thank you to the entire Angular team and community for such a great framework to build upon. If you have any questions, please let me know by opening an issue here.

| Type | Info | | :----------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------- | | | [email protected] | | | https://github.com/sponsors/CodyTolene | | | https://www.buymeacoffee.com/codytolene | | | bc1qfx3lvspkj0q077u3gnrnxqkqwyvcku2nml86wmudy7yf2u8edmqq0a5vnt |

Fin. Happy programming friend!

Cody Tolene