Table
<afp-table>
A table component for displaying tabular data with support for sorting, selection and pagination.
Examples #
Alignment #
Use the alignment attribute to set the alignment of the column content. The available options are start, center, and end.
Width #
Use the width attribute to set a fixed width for a column.
Clickable Cells #
Use the clickable attribute to make a column clickable. You can listen for the afp-click event to handle clicks on the cells.
Clickable Row #
Use the clickableRow (clickablerow) property to make the entire row clickable. You can listen for the afp-row-click event to handle clicks on the rows.
Interactive controls rendered inside a cell (switches, buttons, inputs, links, …) do not trigger the row click, so you can use them to control something in the row without also firing afp-row-click. In the example below the toggle can be clicked independently of the row.
Sortable #
Use the sortable attribute to make a column sortable. By default, the component will sort the column based on the value of the key property, but you can also provide a custom sorting function using the sortValue and sortType property.
Filterable #
Use the filterable attribute to enable column filtering. A Filter button is rendered above the table; clicking it opens a dialog with a control for every column that declares a filter type. After confirming, the active filters are shown as removable tags (each can be cleared via its x, or all at once via Reset all). Listen for the afp-filter-change event to react to filter changes.
Supported filter types:
text— contains match (case-insensitive)select— match any of the chosen options from a dropdownnumber— min/max rangedate— from/to rangeboolean— tri-state via a radio group (any / yes / no)
For select filters, define the available options with filterOptions ([{ label, value }]). Alternatively, set filterOptionsAuto to derive the distinct values automatically from the data — when both are set, filterOptions wins.
Two more per-column options refine filtering: filterLabel overrides the label shown in the dialog and on the filter tags, and filterValue (via JavaScript) matches against a custom value when it differs from the rendered cell. The example below uses explicit filterOptions together with a custom filterLabel.
Set hidden: true on a column to define a filter-only column: it is excluded from the rendered table (header and cells) but still appears in the filter dialog. In the example below the region column can be filtered but is never shown in the table.
Provide a filters object to preset default filters. It is keyed by column key; each value's shape depends on the filter type (select → array of values, text → string, number → { min, max }, date → { from, to }, boolean → { bool }). The example below starts pre-filtered to the EMEA region.
Use the maxFilterTags (maxfiltertags) attribute to limit how many active filter tags are shown. Once exceeded, the remaining filters collapse into a single +X overflow tag that opens the filter dialog when clicked (or activated via keyboard). A value of 0 (default) shows all tags. Apply a few filters in the example below to see the overflow tag appear.
Searchable #
Use the searchable attribute to render a full-text search input in the toolbar above the table. The query is matched case-insensitively against the values of all columns (every word must be found in at least one column). Searching works on the raw data values, not the rendered cell content.
Exclude a column from the search with searchable: false, or provide a searchValue (via JavaScript) to search a custom representation of the value.
searchable and filterable can be combined — the search input sits on the left of the toolbar and the filter button on the right.
Loading #
Use the loading attribute to show a spinner overlay on top of the table while data is being (re)loaded. Existing rows stay visible (dimmed) underneath and the container is marked aria-busy.
Pending #
Use the pending attribute for the initial load, when no data is available yet. The table renders shimmering skeleton rows in place of real rows (and the empty state), hinting at the layout while data is fetched. Use loading instead to overlay a spinner on already-loaded data.
Selectable #
Use the selectable attribute to make rows selectable. You can listen for the afp-select-change event to handle row selection.
You can also use the selectedBg (selectedbg) attribute to apply a background color to selected rows.
Pagination #
Use the pagination attribute to enable pagination for the table. You can use the page and pageSize (pagesize) attributes to set the initial page and page size.
Provide a pageSizeOptions (pagesizeoptions) array to let users change how many rows are shown per page via a select in the pagination controls. The initially selected value is the current pageSize. The select also stays available when everything fits on a single page, so a larger size can be reverted.
Rendering #
Use the render attribute to provide a custom rendering function for the column cells. You can also use the headerRender to provide a custom rendering function for the column header.
Empty Data #
Use the emptystate attribute to display a message when there is no data to show in the table.
Properties
Learn more about properties.
| Name | Description | Reflects | ||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
data
|
Table data as an array of objects. Each object represents a row, and the properties of the object correspond to the column keys defined in the columns property.
The table will render a row for each object in the data array, and the cells in each row will be populated based on the column definitions.
You can update this property to change the displayed data, and the table will automatically re-render to reflect the changes.
Type
T[]
Default
[] |
|||||||||||||||||||||||||||||||||||||||||||||
columns
|
Column definitions for the table. Each column is defined by an object that specifies the key, header, sorting behavior, and rendering logic for that column.
Type
AfpTableColumn
Default
[] |
|||||||||||||||||||||||||||||||||||||||||||||
selectable
|
Enables row selection with checkboxes.
When set to true, a selection column with checkboxes will be added to the table,
allowing users to select individual rows or all rows at once using the header checkbox.
Type
boolean
Default
false |
|
||||||||||||||||||||||||||||||||||||||||||||
selectedBg
selectedbg
|
When set to true, selected rows will have a different background color to visually indicate their selection state.
This works in conjunction with the selectable property, which enables row selection functionality.
Type
boolean
Default
false |
|
||||||||||||||||||||||||||||||||||||||||||||
clickableRow
clickablerow
|
Enables row click events. When set to true, clicking on a cell that is marked as clickable will
emit an 'afp-row-click' event with the corresponding row data in the event detail.
This allows for interactive behavior when users click on specific cells in the table.
Type
boolean
Default
false |
|
||||||||||||||||||||||||||||||||||||||||||||
pagination
|
Enables pagination for the table. When set to true, the table will display a subset of the data based
on the current page and page size, and pagination controls will be rendered to allow users to navigate between pages.
The pagination behavior is controlled by the page and pageSize properties,
which determine the current page number and the number of items displayed per page, respectively.
Type
boolean
Default
false |
|
||||||||||||||||||||||||||||||||||||||||||||
page
|
Current page number (1-based index). This property is used when pagination is enabled to determine which subset of the data to display.
Type
number
Default
1 |
|
||||||||||||||||||||||||||||||||||||||||||||
pageSize
pagesize
|
Number of items to display per page when pagination is enabled. This property determines how many rows of data are shown on each page of the table.
Type
number
Default
25 |
|
||||||||||||||||||||||||||||||||||||||||||||
pageSizeOptions
pagesizeoptions
|
Optional list of selectable page sizes. When provided (and pagination is enabled), a page-size select is
rendered in the pagination controls, letting the user switch how many rows are shown per page. The
initially selected value is the current `pageSize`. When omitted or empty, no select is shown and the
page size stays fixed at `pageSize`.
Type
number[]
Default
[] |
|||||||||||||||||||||||||||||||||||||||||||||
rowDisabled
|
Set row disabled state based on row data.
Type
(row: T) => boolean | undefined
|
|||||||||||||||||||||||||||||||||||||||||||||
emptyState
emptystate
|
Custom HTML content rendered when the table has no visible rows. The value is treated as HTML and
rendered into the empty state cell. When omitted, a default text is shown instead (the "no results"
message when filters are active, otherwise "no data").
Type
string
Default
'' |
|||||||||||||||||||||||||||||||||||||||||||||
sortIconUp
sorticonup
|
Name of the icon used for ascending sort state.
This value is passed to the `name` attribute of the internal `afp-icon`.
Type
string
Default
'arrow-up-short' |
|
||||||||||||||||||||||||||||||||||||||||||||
sortIconDown
sorticondown
|
Name of the icon used for descending sort state.
This value is passed to the `name` attribute of the internal `afp-icon`.
Type
string
Default
'arrow-down-short' |
|
||||||||||||||||||||||||||||||||||||||||||||
sortIconDefault
sorticondefault
|
Name of the icon used for the default unsorted state.
This value is passed to the `name` attribute of the internal `afp-icon`.
Type
string
Default
'arrow-down-short' |
|
||||||||||||||||||||||||||||||||||||||||||||
pageIconBack
pageiconback
|
Name of the icon used for the previous-page pagination button.
This value is passed to the `name` attribute of the internal `afp-icon`.
Type
string
Default
'chevron-left' |
|
||||||||||||||||||||||||||||||||||||||||||||
pageIconNext
pageiconnext
|
Name of the icon used for the next-page pagination button.
This value is passed to the `name` attribute of the internal `afp-icon`.
Type
string
Default
'chevron-right' |
|
||||||||||||||||||||||||||||||||||||||||||||
filterable
|
Enables column filtering. When set to true, a filter bar with a "Filter" button is rendered above the table.
Clicking the button opens a dialog with a control for every column that defines a `filter` type in its
column definition. Confirmed filters are shown as removable tags and narrow down the displayed rows.
Filtering is applied client-side before sorting and pagination.
Type
boolean
Default
false |
|
||||||||||||||||||||||||||||||||||||||||||||
searchable
|
Enables full-text search. When set to true, a search input is rendered in the toolbar above the table.
The query is matched (case-insensitive, AND across words) against the values of all columns that are not
excluded via the column's `searchable: false`. Use a column's `searchValue` to search a custom
representation. Searching is applied client-side before sorting and pagination.
Type
boolean
Default
false |
|
||||||||||||||||||||||||||||||||||||||||||||
loading
|
Shows a loading state. When set to true, a spinner overlay is rendered on top of the table and the
container is marked `aria-busy`, so existing rows stay visible (dimmed) while data is (re)loaded.
Type
boolean
Default
false |
|
||||||||||||||||||||||||||||||||||||||||||||
pending
|
Shows a skeleton placeholder state for the initial load, when no data is available yet. When set to true,
the table renders shimmering skeleton rows in place of real rows (and the empty state), giving a sense of
the layout while data is being fetched. Use `loading` instead to overlay a spinner on already-loaded data.
Type
boolean
Default
false |
|
||||||||||||||||||||||||||||||||||||||||||||
filterIcon
filtericon
|
Name of the icon used for the filter button.
This value is passed to the `name` attribute of the internal `afp-icon`.
Type
string
Default
'funnel' |
|
||||||||||||||||||||||||||||||||||||||||||||
maxFilterTags
maxfiltertags
|
Maximum number of active filter tags to display before collapsing the rest into a single overflow
tag (e.g. "+2"). The hidden filters are listed in a tooltip on that overflow tag. A value of `0`
(the default) shows all tags without collapsing.
Type
number
Default
0 |
|
||||||||||||||||||||||||||||||||||||||||||||
filters
|
The currently applied filters, keyed by column key. Set this to preselect filters (e.g. default filters
on initial render); it is also updated internally as the user edits filters via the dialog and tags.
Each value's shape depends on the column's filter type — see AfpTableFilterValue.
Type
AfpTableFilters
Default
{} |
Methods
Learn more about using methods.
| Name | Description | Arguments |
|---|---|---|
setPage
|
Sets the current page number and emits a 'afp-page-change' event if the page has changed. The event detail includes the new page number, page size, total pages, and total items.
|
next<number>
— The new page number to set. This should be a 1-based index representing the desired page to navigate to.
|
setPageSize
|
Sets the number of items per page, resets to the first page and emits an 'afp-page-size-change' event.
Used by the page-size select rendered when `pageSizeOptions` is provided.
|
next<number>
— The new page size.
|
getSelectedRows
|
This method can be used by external code to retrieve the current selection state of the table when the selectable property is enabled.
|
- |
clearSelection
|
This method can be used by external code to clear all selections in the table when the selectable property is enabled.
It clears the selectedRows Set and emits a selection change event to notify any listeners about the update.
|
- |
selectRow
|
This method can be used by external code to programmatically select or deselect a specific row based on a property key and value when the selectable property is enabled.
|
key<keyof T>
— The property name used to identify the row
id<string | number>
— The value to match against the row property
checked<boolean>
— Whether the row should be selected or not
|
selectAll
|
This method can be used by external code to programmatically select or deselect all rows in the table when the selectable property is enabled.
|
checked<boolean>
— Whether all rows should be selected or deselected
|
openFilters
|
Opens the filter dialog, seeding the draft filters from the currently applied filters.
|
- |
closeFilters
|
Closes the filter dialog without applying the draft changes.
|
- |
removeFilter
|
Removes the filter for a single column and re-applies the remaining filters.
|
key<string>
— The column key whose filter should be removed.
|
clearFilters
|
Clears all active filters and emits an 'afp-filter-change' event.
|
- |
getFilters
|
Returns a copy of the currently active filters.
|
- |
Events
Learn more about events.
| Name | Return | Description |
|---|---|---|
afp-sort-change
|
{sortKey: string, sortDir: string}
|
Emitted when the sorting of the table changes, providing the new sort key and direction in the event detail.
|
afp-filter-change
|
AfpTableFilters
|
Emitted when the active filters change (when filterable is true), providing the current filter map in the event detail.
|
afp-page-change
|
{ page: number, pageSize: number, totalPages: number, totalItems: number}
|
Emitted when the page changes (when pagination is true), providing the new page number, page size, total pages, and total items in the event detail.
|
afp-page-size-change
|
{ page: number, pageSize: number, totalPages: number, totalItems: number}
|
Emitted when the page size changes via the page-size select (when pageSizeOptions is provided), providing the new page (reset to 1), page size, total pages, and total items in the event detail.
|
afp-click
|
T
|
Emitted when a cell marked as clickable is clicked, providing the corresponding row data in the event detail.
|
afp-row-click
|
T
|
Emitted when a row is clicked (when clickableRow is true), providing the corresponding row data in the event detail.
|
afp-select-change
|
T
|
Emitted when the selection of rows changes (when selectable is true), providing an array of the currently selected rows in the event detail.
|
Internationalization
Learn more about internationalization.
| Key | Description |
|---|---|
table.pagination.total-items
|
The total item count shown in the pagination info (receives the count).
|
table.pagination.selected
|
The selected-rows count shown in the pagination info when selectable (receives the count).
|
table.pagination.page
|
The current/total page indicator in the pagination controls (receives current page and total pages).
|
table.pagination.per-page
|
The aria-label of the page-size select shown when pageSizeOptions is provided.
|
table.filter.button
|
The label of the filter button shown above the table when filterable.
|
table.filter.dialog-title
|
The header title of the filter dialog.
|
table.filter.apply
|
The label of the apply button in the filter dialog.
|
table.filter.cancel
|
The label of the cancel button in the filter dialog.
|
table.filter.reset
|
The label of the reset-all action that clears every active filter.
|
table.filter.select-placeholder
|
The placeholder of the select control for a `select` filter.
|
table.filter.min
|
The placeholder of the lower-bound input for a `number` filter.
|
table.filter.max
|
The placeholder of the upper-bound input for a `number` filter.
|
table.filter.from
|
The aria-label of the start-date input for a `date` filter.
|
table.filter.to
|
The aria-label of the end-date input for a `date` filter.
|
table.filter.bool-all
|
The "any" option label of the radio group for a `boolean` filter.
|
table.filter.bool-yes
|
The "yes" option label of the radio group for a `boolean` filter.
|
table.filter.bool-no
|
The "no" option label of the radio group for a `boolean` filter.
|
table.filter.show-all
|
The aria-label of the overflow tag that opens the dialog when filter tags are collapsed.
|
table.empty.no-data
|
The default empty-state text shown when the table has no rows and no filters are active.
|
table.empty.no-results
|
The default empty-state text shown when active filters or a search query match no rows.
|
table.search.placeholder
|
The placeholder of the full-text search input shown when searchable.
|
table.loading
|
The aria-label of the loading overlay shown when the loading property is true.
|
CSS Custom Properties
| Name | Description | Default |
|---|---|---|
--afp-table-border-radius
|
The border radius applied to the table corners.
|
--afp-border-radius-m
|
--afp-table-border-width
|
The width of the table borders.
|
--afp-border-width-s
|
--afp-table-border-color
|
The color of the table borders.
|
--afp-color-surface-border-subtle
|
--afp-table-action-color
|
The color used for interactive elements in the table (e.g., sort indicators, selection checkboxes).
|
--afp-color-surface-elevated
|
--afp-table-padding
|
The padding applied to table cells.
|
--afp-space-xs
|
--afp-table-selection-color
|
The background color applied to selected rows when selectedBg is true.
|
--afp-color-surface-elevated
|
--afp-table-highlight-color
|
The background color applied to highlighted rows based on the column's highlighted function.
|
--afp-color-warning-fill-subtle
|
--afp-table-disabled-color
|
The background color applied to disabled rows based on the rowDisabled function.
|
--afp-color-error-fill-subtle
|
--afp-table-selection-width
|
The width of the selection column when selectable is true.
|
--afp-size-xl
|
Dependencies
The component automatically brings in the listed items, including any nested dependencies that may exist.
| Component | CSS Part Prefix |
|---|---|
|
|
icon
- The icon component.
|
|
|
checkbox
- The checkbox component.
|
|
|
button
- The button component.
|
|
|
dialog
- The dialog component.
|
|
|
tag
- The tag component.
|
|
|
select
- The select component.
|
|
|
option
- The option component.
|
|
|
input
- The input component.
|
|
|
radio-group
- The radio-group component.
|
|
|
radio
- The radio component.
|
|
|
spinner
- The spinner component.
|
Importing
Using the bundle is the recommended method to include components. If you’d rather handle imports manually, you can use the code examples below.
import '@afp-design-system/core/dist/components/table/table.js';