A data table web component that renders rows and columns from a declarative column definition. Supports pagination, grouped columns, conditional cell styling, value mapping, and multiple cell display modes (plain text, link, boolean icon, secret, tooltip, button, image, tag).
| Usage | Tag |
|---|---|
| Angular component | <mfp-declarative-table> |
| Web Component (framework-agnostic) | <mfp-wc-declarative-table> |
Include the bundle and set properties via JavaScript. Because the component uses Shadow DOM, no extra CSS setup is needed.
<!DOCTYPE html>
<html>
<head>
<script type="module" src="declarative-table.js" />
</head>
<body>
<mfp-wc-declarative-table id="table"></mfp-wc-declarative-table>
<script type="module">
const table = document.getElementById('table');
table.columns = [
{ label: 'Name', property: 'metadata.name' },
{ label: 'Status', property: 'status.phase' },
];
table.resources = [
{ metadata: { name: 'pod-1' }, status: { phase: 'Running' } },
{ metadata: { name: 'pod-2' }, status: { phase: 'Pending' } },
];
table.trackByPath = 'metadata.name';
</script>
</body>
</html>
columns,resources, andtrackByare JavaScript properties, not HTML attributes. They must be set programmatically after the element is available in the DOM.
import { DeclarativeTable } from '@openmfp/ngx';
import { TableFieldDefinition } from '@openmfp/ngx';
@Component({
imports: [DeclarativeTable],
template: `
<mfp-declarative-table
[columns]="columns"
[resources]="resources"
[trackByPath]="trackByPath"
[hasMore]="hasMore"
[loading]="loading"
[error]="error"
[paginationLimit]="pageSize"
[totalItemsCount]="total"
(tableRowClicked)="onRowClick($event)"
(loadMoreResources)="loadMore()"
(paginationLimitChanged)="onPageSizeChange($event)"
(retry)="reload()"
/>
`,
})
export class MyComponent {
columns: TableFieldDefinition[] = [
{ label: 'Name', property: 'metadata.name' },
{ label: 'Status', property: 'status.phase' },
];
resources = [...];
trackByPath = 'metadata.name';
hasMore = false;
pageSize = 10;
total = 0;
}| Input | Type | Required | Default | Description |
|---|---|---|---|---|
overflowMode |
'Scroll' | 'Popin' |
no | 'Scroll' |
Horizontal overflow behavior |
appearance |
'default' | 'card' |
no | 'default' |
'card' renders every supplied row as passive, suppresses row click events and hides the pager, page-size selector and load-more controls. |
columns |
TableFieldDefinition[] |
yes | — | Column definitions |
resources |
GenericResource[] |
yes | — | Data rows |
trackByPath |
string |
no | 'id' |
JSONPath (dot-notation) into each resource used as the row identity key |
totalItemsCount |
number |
no | — | Total count of all items across pages |
paginationLimit |
number |
no | 5 |
Rows per page shown in the page-size selector |
hasMore |
boolean |
no | false |
Show the load-more trigger at the bottom |
loadMode |
'scroll' | 'button' | 'pager' |
no | 'button' |
Load strategy: 'button' shows a load-more button, 'scroll' triggers on scroll, 'pager' renders numbered pagination controls |
loadMoreButtonText |
string |
no | 'Load More' |
Label shown on the load-more button (used when loadMode is 'button') |
height |
number |
no | — | Fixed height in pixels. Combined with loadMode: 'scroll', enables scroll-based loading. Not needed just to get a scrolling table — see Scrolling and the sticky header. |
currentPage |
number |
no | 1 |
1-based current page. Only used when loadMode is 'pager' |
permissions |
Record<string, string[]> |
no | — | Per-row permission map keyed by resource.id. Passed to every cell's mfp-resource-field to evaluate requirePermission on each column definition. |
loading |
boolean |
no | false |
Shows the table loading indicator and suppresses the empty state while data is loading. |
loadingDelay |
number |
no | 1000 |
Delay in milliseconds before the loading indicator is displayed. |
error |
TableErrorConfig | null |
no | null |
Replaces rows and the empty state with an error illustrated message. When null or absent the table renders normally. See TableErrorConfig. |
| Event | Detail payload | Description |
|---|---|---|
tableRowClicked |
row object | Fires when a row is clicked |
buttonClick |
{ event, field, resource } |
Fires when a button cell is clicked |
loadMoreResources |
— | Fires when the user triggers load more |
paginationLimitChanged |
number |
Fires when the user changes the page size |
pageChange |
number |
Fires when the user selects a page (loadMode: 'pager') |
retry |
— | Fires when the user selects Retry in the error state |
Listening to events from a web component:
table.addEventListener('tableRowClicked', (e) => console.log(e.detail));
table.addEventListener('loadMoreResources', () => fetchNextPage());
table.addEventListener('retry', () => reload());
table.addEventListener('paginationLimitChanged', (e) => {
table.paginationLimit = e.detail;
});
table.addEventListener('buttonClick', (e) => {
const { field, resource } = e.detail;
console.log('Button clicked for', resource);
});interface TableFieldDefinition {
label?: string;
property?: string; // dot-notation path into the resource object
jsonPathExpression?: string; // explicit JSONPath expression
propertyField?: PropertyField; // access a sub-key with optional transforms
value?: string; // static fallback value
uiSettings?: UiSettings;
columnSettings?: TableColumnSettings;
group?: {
name: string; // columns sharing the same name are merged into one header
label?: string; // label for the merged header
delimiter?: string; // separator between values (default: space)
multiline?: boolean; // render values on separate lines instead
};
}Values are resolved in this order:
jsonPathExpression— evaluated as a JSONPath query against the resource (e.g.$.spec.containers[0].image)property— dot-notation path; a$.prefix is added automatically if missingpropertyField— accessesresource[property][propertyField.key]with optional transformsvalue— static string, used as a fallback when the resource yields no value
Examples:
// Simple dot-notation
{ label: 'Name', property: 'metadata.name' }
// Explicit JSONPath
{ label: 'Image', jsonPathExpression: '$.spec.containers[0].image' }
// Sub-key with transform
{ label: 'Created', property: 'metadata', propertyField: { key: 'creationTimestamp', transform: ['uppercase'] } }
// Static fallback when property may be absent
{ label: 'Message', property: 'status.message', value: 'N/A' }Transforms can be chained and are applied left to right.
| Transform | Effect |
|---|---|
uppercase |
hello → HELLO |
lowercase |
HELLO → hello |
capitalize |
hello → Hello |
encode |
Base64-encodes the value |
decode |
Base64-decodes the value |
{ property: 'metadata', propertyField: { key: 'name', transform: ['capitalize'] } }By default a cell renders its value as plain text. Use uiSettings.displayAs to change the rendering:
displayAs |
Renders as |
|---|---|
| (unset) | Plain text |
'secret' |
Masked value with a toggle-visibility button |
'boolIcon' |
Check / X icon for "true" / "false" string values |
'link' |
Clickable anchor; href from linkSettings.link template or field value; visible text from linkSettings.text or field value |
'tooltip' |
Text with an info icon; the full value appears on hover |
'alert' |
Alert-styled text |
'img' |
<img> element using the value as src |
'button' |
Action button (requires buttonSettings) |
'tag' |
One <ui5-tag> chip per value (split by tagSettings.valueSeparator, default ','); also accepts an array of values |
Link href resolution. When
linkSettings.linkis set,{{path}}placeholders are substituted and then the result is resolved against the current page URL (window.location.href, treated as a directory): absolute URLs (e.g.https://…,mailto:…) are returned unchanged; a leading/resolves from the origin root; no leading slash is appended to the current path. See docs/resource-field.md for full details and examples.
Add a copy-to-clipboard icon to any cell:
{ label: 'ID', property: 'metadata.uid', uiSettings: { withCopyButton: true } }Set overflowMode to 'Popin' to move columns below each row when space runs out ('Scroll' by default). In columnSettings, use minWidth (default 3rem, applies to automatic/percentage widths), importance (higher stays visible longer, default 0), popinText (defaults to the column/group label), and popinHidden (default false; hides the value on narrow screens). Grouped columns use the first field's settings. For existing configurations, uiSettings.columnWidth remains supported; columnSettings.width takes precedence when provided.
Set an explicit width on a column header cell:
{ label: 'Actions', columnSettings: { width: '10rem' } }UI5 constraint. The value must be a valid CSS
<length>—px,rem,em,%, orcalc(). Sizing keywords such asmin-contentandmax-contentare rejected by UI5 and fall back to equal-stretch distribution across all columns.
Control the horizontal alignment of cell content using uiSettings.align. The value maps directly to the CSS justify-content property of the cell's flex wrapper.
| Value | Effect |
|---|---|
'start' |
Left-aligned (default browser behaviour) |
'center' |
Centred |
'end' |
Right-aligned |
{
uiSettings: {
displayAs: 'button',
align: 'end',
buttonSettings: { icon: 'delete', design: 'Transparent', action: 'delete' },
},
group: { name: 'actions', label: '' },
}For group columns the alignment is driven by the first field's uiSettings.align.
{
label: 'Actions',
property: 'metadata.name',
uiSettings: {
displayAs: 'button',
buttonSettings: {
text: 'Open',
icon: 'action',
design: 'Emphasized', // 'Default' | 'Positive' | 'Negative' | 'Transparent' | 'Emphasized' | 'Attention'
action: 'navigate', // 'navigate' | 'openInModal'
},
},
}A buttonClick event fires with { event, field, resource } when clicked.
Columns that share the same group.name are collapsed into a single table column. Their values are displayed together, separated by group.delimiter or on separate lines when group.multiline is true.
columns = [
{
label: 'First name',
property: 'firstName',
group: { name: 'fullName', label: 'Full Name', delimiter: ' ' },
},
{
label: 'Last name',
property: 'lastName',
group: { name: 'fullName' },
},
{ label: 'Email', property: 'email' },
];The above produces two visible columns: Full Name and Email.
The first field in a group sets the column-level configuration. columnSettings.width controls the <ui5-table-header-cell> width; uiSettings.align controls justify-content of the cell content wrapper. The column header text comes from group.label (or group.name if omitted) of the first field. These values on subsequent fields in the same group are ignored.
columns = [
// First field — drives column width and right-alignment for the whole group
{
columnSettings: { width: '8rem' },
uiSettings: {
displayAs: 'button',
align: 'end',
buttonSettings: { icon: 'edit', design: 'Transparent', action: 'edit' },
},
group: { name: 'actions', label: '', multiline: false },
},
// Second field — columnSettings and uiSettings.align are ignored here
{
uiSettings: {
displayAs: 'button',
buttonSettings: {
icon: 'decline',
design: 'Transparent',
action: 'delete',
},
},
group: { name: 'actions', label: '', multiline: false },
},
];Apply inline styles to a cell when its value meets a condition:
{
label: 'Status',
property: 'status.phase',
uiSettings: {
cssRules: [
{ if: { condition: 'equals', value: 'Running' }, styles: { color: 'green' } },
{ if: { condition: 'equals', value: 'Failed' }, styles: { color: 'red', fontWeight: 'bold' } },
{ if: { condition: 'contains', value: 'Pending' }, styles: { color: 'orange' } },
],
},
}Available conditions: equals, notEquals, greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual, contains.
cssCustomization applies static styles unconditionally:
uiSettings: {
cssCustomization: {
fontStyle: 'italic';
}
}Map a cell's raw value to a display string. The first matching rule wins; when no rule matches the raw value is shown unchanged.
{
label: 'Activity',
property: 'metrics.score',
uiSettings: {
valueRules: [
{ if: { condition: 'lessThan', value: '20' }, then: 'Low' },
{ if: { condition: 'lessThan', value: '60' }, then: 'Medium' },
{ if: { condition: 'greaterThanOrEqual', value: '60' }, then: 'High' },
],
cssRules: [
{ if: { condition: 'lessThan', value: '20' }, styles: { color: 'red' } },
{ if: { condition: 'greaterThanOrEqual', value: '20' }, styles: { color: 'darkorange' } },
{ if: { condition: 'greaterThanOrEqual', value: '60' }, styles: { color: 'green' } },
],
},
}When hasMore is true a load-more trigger appears at the bottom of the table. The trigger behaviour is controlled by loadMode:
loadMode: 'button'(default) — a button labelled withloadMoreButtonTextis shown. Clicking it firesloadMoreResources.loadMode: 'scroll'— loading is triggered automatically as the user scrolls. Setheightto constrain the table height and enable scroll detection.loadMode: 'pager'— numbered pagination controls are shown instead of a load-more trigger. ProvidetotalItemsCountand (optionally)currentPage; the table firespageChangewith the 1-based page number when the user navigates.paginationLimitsets the page size.
A page-size selector is always present.
The component lays itself out as a column: the ui5-table sits above the page-size/count footer. By default it is content-sized — the table grows with its rows, so a load-more click makes it taller and the load-more trigger always sits directly under the last row.
Set height to constrain it instead. The ui5-table then scrolls its data rows inside that height, while the column header row and the footer stay put.
height sizes the ui5-table box alone — the page-size footer sits below it — so a table given height: 200 renders about 260 px tall once the footer is counted. DeclarativeTableCard does that arithmetic for you when it is given a contentHeight, which is how a table card fits a dashboard tile.
The header row is sticky in both cases; where the table does not scroll that has no visible effect. Earlier versions made it sticky only for loadMode: 'scroll' and a set height, which left the column headers scrolling out of view whenever the table scrolled for any other reason.
Any plain object works as a resource. Three optional fields control table behaviour:
| Field | Type | Description |
|---|---|---|
id |
string |
Default trackByPath target; used as the row identity key unless overridden |
isAvailable |
boolean |
When false, the row is rendered as non-interactive |
accessibleName |
string |
Accessible label attached to the row element |
Controls the content of the error illustrated message shown when error is set.
interface TableErrorConfig {
status?: number; // HTTP status code — 403 switches to the 'UnsuccessfulAuth' illustration
title?: string; // Heading text rendered above the error illustration
message?: string; // Subtitle text with additional context
withRetryButton?: boolean; // When true, a Retry button is shown; clicking it emits the `retry` output
retryButtonText?: string; // Button label, defaults to 'Retry'
}Examples:
// Generic error — no retry
error = {};
// Generic error with retry
error = { withRetryButton: true };
// 403 Forbidden — distinct illustration, no retry
error = {
status: 403,
title: 'Access Denied',
message: 'You do not have permission to view this resource.',
};
// Generic error with all fields
error = {
status: 500,
title: 'Failed to load data',
message: 'An unexpected error occurred. Please try again.',
withRetryButton: true,
};All interactive elements carry data-testid attributes for reliable E2E targeting. See docs/test-ids.md for the full naming convention.
| Element | data-testid |
Notes |
|---|---|---|
| Table element | generic-table |
|
| Header cell | generic-table-header-{column} |
column = group.name or property |
| Row | generic-table-row-{i} |
i = 0-based index |
| Cell (simple column) | generic-table-cell-{i}-{property} |
|
| Cell (grouped column) | generic-table-cell-{i}-{group} |
group = group.name |
| Group sub-value | generic-table-cell-{i}-{group}-{property} |
|
| No-data state | generic-table-view-nodata |
Shown when resources is empty |
| Error state | generic-table-view-error |
Shown when error is set |
| Error title | generic-table-error-title |
Shown when error.title is set |
| Retry button | generic-table-retry |
Shown when error.withRetryButton is true |
| Load-more trigger | generic-table-growing |
Shown when hasMore is true |
| Page-size select | generic-table-pagination-select |
Always present |