Intelligence Community Design System ICDS Get started Accessibility Styles Components Patterns Community
Show navigation section

Data table

Guidance Code

Component demo

Interactive example

<ic-data-tablecaption="Basic Table"></ic-data-table>

Data table details

Props

All components also accept native properties supported by the DOM, such asclassName and style .

Name Description Default
Property caption
Attribute caption

The title for the table only visible to screen readers.

Required type: string
Property columns

The column headers for the table.

Required type: IcDataTableColumnObject[]
Property columnHeaderTruncation
Attribute column-header-truncation

Determines whether the column header should be truncated and display a tooltip. Default isfalse .

type: boolean
false
Property data

The row content for the table.

type: IcDataTableDataType[] - IcDataTableDataType[] | undefined
Property density
Attribute density

Set the density of the table including font and padding.

type: IcDataTableDensityOptions - "default" | "dense" | "spacious"
"default"
Property disableAutoSort
Attribute disable-auto-sort

Iftrue , the built in sort functionality will be disabled. For example, if rows will already be sorted from an external source.

type: boolean - boolean | undefined
false
Property embedded
Attribute embedded

Applies a border to the table container.

type: boolean
false
Property globalRowHeight
Attribute global-row-height

Sets the row height on all rows in the table that aren't set using thevariableRowHeight method.

type: IcDataTableRowHeights - "auto" | number
"auto"
Property height
Attribute height

Sets the table height. Can be set toauto or a specific value inpx ,rem , or% .

type: string - string | undefined
Property hideColumnHeaders
Attribute hide-column-headers

Iftrue , column headers will not be visible.

type: boolean - boolean | undefined
false
Property loading
Attribute loading

When set totrue , the full table will show a loading state, featuring a radial indicator.

type: boolean
false
Property loadingOptions

Sets the props for the circular loading indicator used in the loading state.

type: { description?: string; label?: string; labelDuration?: number; max?: number; min?: number; progress?: number; monochrome?: boolean; overlay?: boolean; } - undefined | { description?: string | undefined; label?: string | undefined; labelDuration?: number | undefined; max?: number | undefined; min?: number | undefined; progress?: number | undefined; monochrome?: boolean | undefined; overlay?: boolean | undefined; }
Property maxWidth
Attribute max-width

Sets the maximum width of the data table. Can be set inpx ,rem , or% .

type: string - string | undefined
Property minWidth
Attribute min-width

Sets the minimum width of the data table. Can be set inpx ,rem , or% .

type: string - string | undefined
Property minimumLoadingDisplayDuration
Attribute minimum-loading-display-duration

The minimum amount of time theloading state displays for before showing the data. Used to prevent flashing in the component.

type: number
1000
Property paginationBarOptions

Sets the props for the built-in pagination bar. If thepagination-bar slot is used then this prop is ignored.

type: IcPaginationBarOptions
{ alignment: "right", hideAllFromItemsPerPage: false, hideRangeLabel: false, itemLabel: "Item", itemsPerPageOptions: [ { label: "10", value: "10" }, { label: "25", value: "25" }, { label: "50", value: "50" }, ], monochrome: false, pageLabel: "Page", rangeLabelType: "page", selectedItemsPerPage: 10, setToFirstPageOnPaginationChange: false, showGoToPageControl: true, showItemsPerPageControl: true, type: "simple", }
Property rowSelection
Attribute row-selection

Iftrue , a checkbox column will be displayed to the left of the table which allows multiple rows to be selected.

type: boolean
false
Property showPagination
Attribute show-pagination

Iftrue , adds a pagination bar to the bottom of the table.

type: boolean - boolean | undefined
false
Property sortOptions

Sets the order columns will be sorted in and allows for 'default' sorts to be added.

type: { sortOrders: IcDataTableSortOrderOptions[]; defaultColumn?: string; } - { sortOrders: IcDataTableSortOrderOptions[]; defaultColumn?: string | undefined; }
{ sortOrders: ["unsorted", "ascending", "descending"], defaultColumn: "", }
Property sortable
Attribute sortable

Iftrue , allows table columns to be sorted using applied sort buttons.

type: boolean - boolean | undefined
false
Property stickyColumnHeaders
Attribute sticky-column-headers

Iftrue , column headers will remain at the top of the table when scrolling vertically.

type: boolean
false
Property stickyRowHeaders
Attribute sticky-row-headers

Iftrue , row headers will remain to the left when scrolling horizontally.

type: boolean
false
Property tableLayout
Attribute table-layout

Sets the layout of the table

type: "fixed" | "auto" - "auto" | "fixed" | undefined
"fixed"
Property theme
Attribute theme

Sets the theme color to the dark or light theme color. "inherit" will set the color based on the system settings or ic-theme component.

type: IcThemeMode - "dark" | "inherit" | "light" | undefined
"inherit"
Property truncationPattern
Attribute truncation-pattern

Sets the method used to truncate long text in cells where textWrap isfalse . Thetooltip truncation pattern allows the overflowing text to be seen in a tooltip. Theshow-hide truncation pattern allows the overflowing text to be shown and hidden using the ic-typography "See more"/"See less" buttons.

type: IcDataTableTruncationTypes - "show-hide" | "tooltip" | undefined
Property updating
Attribute updating

Iftrue , the table displays a linear loading indicator below the header row to indicate an updating state.

type: boolean
false
Property updatingOptions

Sets the props for the linear loading indicator used in the updating state.

type: { description?: string; max?: number; min?: number; progress?: number; monochrome?: boolean; } - undefined | { description?: string | undefined; max?: number | undefined; min?: number | undefined; progress?: number | undefined; monochrome?: boolean | undefined; }
Property variableRowHeight

Allows for custom setting of row heights on individual rows based on an individual value from thedata prop and the row index. If the function returnsnull , that row's height will be set to theglobalRowHeight property.

type: (params: { [key: string]: any; index: number; }) => IcDataTableRowHeights | null - ((params: { [key: string]: any; index: number; }) => IcDataTableRowHeights | null) | undefined
Property width
Attribute width

Sets the table width. Can be set toauto or a specific value inpx ,rem , or% .

type: string - string | undefined
Property caption
Attribute caption

The title for the table only visible to screen readers.

Required type: string
Property columns

The column headers for the table.

Required type: IcDataTableColumnObject[]
Property columnHeaderTruncation
Attribute column-header-truncation

Determines whether the column header should be truncated and display a tooltip. Default isfalse .

type: boolean
Default: false
Property data

The row content for the table.

type: IcDataTableDataType[] - IcDataTableDataType[] | undefined
Property density
Attribute density

Set the density of the table including font and padding.

type: IcDataTableDensityOptions - "default" | "dense" | "spacious"
Default: "default"
Property disableAutoSort
Attribute disable-auto-sort

Iftrue , the built in sort functionality will be disabled. For example, if rows will already be sorted from an external source.

type: boolean - boolean | undefined
Default: false
Property embedded
Attribute embedded

Applies a border to the table container.

type: boolean
Default: false
Property globalRowHeight
Attribute global-row-height

Sets the row height on all rows in the table that aren't set using thevariableRowHeight method.

type: IcDataTableRowHeights - "auto" | number
Default: "auto"
Property height
Attribute height

Sets the table height. Can be set toauto or a specific value inpx ,rem , or% .

type: string - string | undefined
Property hideColumnHeaders
Attribute hide-column-headers

Iftrue , column headers will not be visible.

type: boolean - boolean | undefined
Default: false
Property loading
Attribute loading

When set totrue , the full table will show a loading state, featuring a radial indicator.

type: boolean
Default: false
Property loadingOptions

Sets the props for the circular loading indicator used in the loading state.

type: { description?: string; label?: string; labelDuration?: number; max?: number; min?: number; progress?: number; monochrome?: boolean; overlay?: boolean; } - undefined | { description?: string | undefined; label?: string | undefined; labelDuration?: number | undefined; max?: number | undefined; min?: number | undefined; progress?: number | undefined; monochrome?: boolean | undefined; overlay?: boolean | undefined; }
Property maxWidth
Attribute max-width

Sets the maximum width of the data table. Can be set inpx ,rem , or% .

type: string - string | undefined
Property minWidth
Attribute min-width

Sets the minimum width of the data table. Can be set inpx ,rem , or% .

type: string - string | undefined
Property minimumLoadingDisplayDuration
Attribute minimum-loading-display-duration

The minimum amount of time theloading state displays for before showing the data. Used to prevent flashing in the component.

type: number
Default: 1000
Property paginationBarOptions

Sets the props for the built-in pagination bar. If thepagination-bar slot is used then this prop is ignored.

type: IcPaginationBarOptions
Default: { alignment: "right", hideAllFromItemsPerPage: false, hideRangeLabel: false, itemLabel: "Item", itemsPerPageOptions: [ { label: "10", value: "10" }, { label: "25", value: "25" }, { label: "50", value: "50" }, ], monochrome: false, pageLabel: "Page", rangeLabelType: "page", selectedItemsPerPage: 10, setToFirstPageOnPaginationChange: false, showGoToPageControl: true, showItemsPerPageControl: true, type: "simple", }
Property rowSelection
Attribute row-selection

Iftrue , a checkbox column will be displayed to the left of the table which allows multiple rows to be selected.

type: boolean
Default: false
Property showPagination
Attribute show-pagination

Iftrue , adds a pagination bar to the bottom of the table.

type: boolean - boolean | undefined
Default: false
Property sortOptions

Sets the order columns will be sorted in and allows for 'default' sorts to be added.

type: { sortOrders: IcDataTableSortOrderOptions[]; defaultColumn?: string; } - { sortOrders: IcDataTableSortOrderOptions[]; defaultColumn?: string | undefined; }
Default: { sortOrders: ["unsorted", "ascending", "descending"], defaultColumn: "", }
Property sortable
Attribute sortable

Iftrue , allows table columns to be sorted using applied sort buttons.

type: boolean - boolean | undefined
Default: false
Property stickyColumnHeaders
Attribute sticky-column-headers

Iftrue , column headers will remain at the top of the table when scrolling vertically.

type: boolean
Default: false
Property stickyRowHeaders
Attribute sticky-row-headers

Iftrue , row headers will remain to the left when scrolling horizontally.

type: boolean
Default: false
Property tableLayout
Attribute table-layout

Sets the layout of the table

type: "fixed" | "auto" - "auto" | "fixed" | undefined
Default: "fixed"
Property theme
Attribute theme

Sets the theme color to the dark or light theme color. "inherit" will set the color based on the system settings or ic-theme component.

type: IcThemeMode - "dark" | "inherit" | "light" | undefined
Default: "inherit"
Property truncationPattern
Attribute truncation-pattern

Sets the method used to truncate long text in cells where textWrap isfalse . Thetooltip truncation pattern allows the overflowing text to be seen in a tooltip. Theshow-hide truncation pattern allows the overflowing text to be shown and hidden using the ic-typography "See more"/"See less" buttons.

type: IcDataTableTruncationTypes - "show-hide" | "tooltip" | undefined
Property updating
Attribute updating

Iftrue , the table displays a linear loading indicator below the header row to indicate an updating state.

type: boolean
Default: false
Property updatingOptions

Sets the props for the linear loading indicator used in the updating state.

type: { description?: string; max?: number; min?: number; progress?: number; monochrome?: boolean; } - undefined | { description?: string | undefined; max?: number | undefined; min?: number | undefined; progress?: number | undefined; monochrome?: boolean | undefined; }
Property variableRowHeight

Allows for custom setting of row heights on individual rows based on an individual value from thedata prop and the row index. If the function returnsnull , that row's height will be set to theglobalRowHeight property.

type: (params: { [key: string]: any; index: number; }) => IcDataTableRowHeights | null - ((params: { [key: string]: any; index: number; }) => IcDataTableRowHeights | null) | undefined
Property width
Attribute width

Sets the table width. Can be set toauto or a specific value inpx ,rem , or% .

type: string - string | undefined

Slots

A slot allows for any type of element or markup to be passed into and rendered within a web component. This creates more flexibility than using a prop which must take a specific type of data.

Content can be slotted into a component by adding it as a top-level child of the component.

Slots can have a name to identify them. These specify which slot the content will be inserted into, and therefore where it will be rendered and how it will be used within the component. The name of the slot to be used can be specified by passing it via a slot attribute on the slotted content.

Read more about slots .


Name Description
Slot empty-state
Content is slotted below the table header when there is no data and the table is not loading.
Slot pagination-bar
A custom ic-pagination-bar can be slotted below the data to provide enhanced control over how the data is interacted with when being fetched externally.
Slot title-bar
A custom ic-data-table-title-bar can be slotted above the column headers to display additional information about the table.
Slot {COLUMN_KEY}-column-icon
The icon slot for a column header.
Slot {COLUMN_KEY}-{ROW_INDEX}[-icon]
Each cell should have its own slot, named using the column tag and the row index, allowing for custom elements to be displayed. Include `-icon` at the end for that cell's icon slot.
Slot empty-state
Content is slotted below the table header when there is no data and the table is not loading.
Slot pagination-bar
A custom ic-pagination-bar can be slotted below the data to provide enhanced control over how the data is interacted with when being fetched externally.
Slot title-bar
A custom ic-data-table-title-bar can be slotted above the column headers to display additional information about the table.
Slot {COLUMN_KEY}-column-icon
The icon slot for a column header.
Slot {COLUMN_KEY}-{ROW_INDEX}[-icon]
Each cell should have its own slot, named using the column tag and the row index, allowing for custom elements to be displayed. Include `-icon` at the end for that cell's icon slot.

Events

All components also accept native events supported by the DOM, such as onClick and onKeyDown .

Name Description Signature
Web component icRowHeightChange
React onIcRowHeightChange
Emitted when the `globalRowHeight` or `variableRowHeight` properties change in the data table.
void
Web component icSelectAllRows
React onIcSelectAllRows
Emitted when all rows are selected or deselected in the data table via the "select all" checkbox.
IcDataTableDataType[]
Web component icSelectedRowChange
React onIcSelectedRowChange
Emitted when the selected row changes in the data table.
{ row: IcDataTableDataType | null; selectedRows: IcDataTableDataType[]; }
Web component icSortChange
React onIcSortChange
Emitted when a column sort button is clicked.
IcSortEventDetail
Web component icRowHeightChange
React onIcRowHeightChange
Emitted when the `globalRowHeight` or `variableRowHeight` properties change in the data table.
void
Web component icSelectAllRows
React onIcSelectAllRows
Emitted when all rows are selected or deselected in the data table via the "select all" checkbox.
IcDataTableDataType[]
Web component icSelectedRowChange
React onIcSelectedRowChange
Emitted when the selected row changes in the data table.
{ row: IcDataTableDataType | null; selectedRows: IcDataTableDataType[]; }
Web component icSortChange
React onIcSortChange
Emitted when a column sort button is clicked.
IcSortEventDetail

Methods

Name Description Signature
Method resetRowHeights
Resets the `globalRowHeight` prop to number or auto and sets the `variableRowHeight` prop to `null`.
resetRowHeights(rowHeight?: number | "auto") => Promise<void>
Method resetRowHeights
Resets the `globalRowHeight` prop to number or auto and sets the `variableRowHeight` prop to `null`.
resetRowHeights(rowHeight?: number | "auto") => Promise<void>

Variants

Embedded

Interactive example

<ic-data-tablecaption="Embedded Table"embedded="true"></ic-data-table>

Dense

Interactive example

<ic-data-tablecaption="Dense Table"density="dense"></ic-data-table>

Spacious

Interactive example

<ic-data-tablecaption="Spacious Table"density="spacious"></ic-data-table>

Sticky column headers

Interactive example

Stick Header Unstick Header
<ic-data-table
caption="Sticky header Table"
sticky-column-headers="true"
></ic-data-table>

Row headers

Interactive example

<ic-data-tablecaption="Row headers"></ic-data-table>

Sortable

Interactive example

<ic-data-tablecaption="Sort"sortable="true"></ic-data-table>

Sort options

Interactive example

<ic-data-tablecaption="Sort Options"sortable="true"></ic-data-table>

Pagination

Interactive example

<ic-data-tablecaption="Pagination"show-pagination="true"></ic-data-table>

Slotted pagination

Interactive example

<ic-data-tablecaption="Slotted pagination bar">
<ic-pagination-barslot="pagination-bar"show-items-per-page-control="true"></ic-pagination-bar>
</ic-data-table>

Column overrides

Interactive example

<ic-data-tablecaption="Column Overrides"></ic-data-table>

Row overrides

Interactive example

<ic-data-tablecaption="Row Overrides"></ic-data-table>

Cell overrides

Interactive example

<ic-data-tablecaption="Cell Overrides"></ic-data-table>

Default Empty State

Interactive example

<ic-data-tablecaption="Default Empty State"></ic-data-table>

Slotted Empty State

Interactive example

Retry
<ic-data-tableid="data-table"caption="Slotted Empty State">
<ic-empty-state
aligned="left"
heading="Data source error"
body="Error loading new data"
>
<ic-buttonslot="actions">Retry</ic-button>
</ic-empty-state>
</ic-data-table>

Loading state

Interactive example

<ic-data-tableid="data-table"caption="Loading State"></ic-data-table>

Updating state

Interactive example

<ic-data-tableid="data-table"caption="Updating State"></ic-data-table>

Interactive example

Delete Delete Delete
<ic-data-tablecaption="Links and Elements in data"></ic-data-table>

Custom icons

Interactive example

<ic-data-tableid="data-table"caption="Custom Icons">
<svg
slot="age-column-icon"
xmlns="http://www.w3.org/2000/svg"
viewBox="0 0 24 24"
>
<path
d="M12 6C13.11 6 14 5.1 14 4C14 3.62 13.9 3.27 13.71 2.97L12 0L10.29 2.97C10.1 3.27 10 3.62 10 4C10 5.1 10.9 6 12 6M18 9H13V7H11V9H6C4.34 9 3 10.34 3 12V21C3 21.55 3.45 22 4 22H20C20.55 22 21 21.55 21 21V12C21 10.34 19.66 9 18 9M19 20H5V17C5.9 17 6.76 16.63 7.4 16L8.5 14.92L9.56 16C10.87 17.3 13.15 17.29 14.45 16L15.53 14.92L16.6 16C17.24 16.63 18.1 17 19 17V20M19 15.5C18.5 15.5 18 15.3 17.65 14.93L15.5 12.8L13.38 14.93C12.64 15.67 11.35 15.67 10.61 14.93L8.5 12.8L6.34 14.93C6 15.29 5.5 15.5 5 15.5V12C5 11.45 5.45 11 6 11H18C18.55 11 19 11.45 19 12V15.5Z"
/>
</svg>
</ic-data-table>

Custom row heights

Interactive example

<ic-data-tableid="data-table"caption="Custom Row Heights"></ic-data-table>

Custom title bar

Interactive example

Add new order

A log kept of all coffee orders to refer back to.

<ic-data-tableid="data-table"caption="Coffee Orders">
<ic-data-table-title-bar
slot="title-bar"
description="A list of all coffee orders in the last year."
metadata="3 items | Updated: 20/03/25"
>
<ic-buttonslot="primary-action">Add new order</ic-button>
<ic-buttonslot="custom-actions"variant="icon"aria-label="Coffee 1">
<svg
xmlns="http://www.w3.org/2000/svg"
height="24"
viewBox="0 -960 960 960"
width="24"
>
<path
d="M180-120q-24 0-42-18t-18-42v-600q0-24 18-42t42-18h600q24 0 42 18t18 42v600q0 24-18 42t-42 18H180Zm0-60h600v-600H180v600Zm56-97h489L578-473 446-302l-93-127-117 152Zm-56 97v-600 600Z"
/>
</svg>
</ic-button>
<ic-buttonslot="custom-actions"variant="icon"aria-label="Coffee 2">
<svg
xmlns="http://www.w3.org/2000/svg"
height="24"
viewBox="0 -960 960 960"
width="24"
>
<path
d="M180-120q-24 0-42-18t-18-42v-600q0-24 18-42t42-18h600q24 0 42 18t18 42v600q0 24-18 42t-42 18H180Zm0-60h600v-600H180v600Zm56-97h489L578-473 446-302l-93-127-117 152Zm-56 97v-600 600Z"
/>
</svg>
</ic-button>
<ic-typographyslot="description"variant="body">
<p>
A log kept of all{' '}
<ic-linkhref="#">coffee orders</ic-link> to refer back to.
</p>
</ic-typography>
</ic-data-table-title-bar>
</ic-data-table>

Truncation - tooltip

Interactive example

<ic-data-tablecaption="Data table truncation - tooltip"truncation-pattern="tooltip"></ic-data-table>

Truncation - show/hide

Interactive example

<ic-data-tablecaption="Data table truncation - show/hide"truncation-pattern="show-hide"></ic-data-table>

Text wrap

Interactive example

<ic-data-tablecaption="Data table text wrap"></ic-data-table>

Columns widths and table sizing

Interactive example

<ic-data-tablecaption="Columns widths and table sizing"table-layout="auto"width="800px"></ic-data-table>

Description and icons within cells

Interactive example

<ic-data-tablecaption="Description and icons within cells"table-layout="auto"></ic-data-table>

Missing cell data

Interactive example

<ic-data-tablecaption="Missing cell data"></ic-data-table>

Last reviewed 21 August 2024 .
Navigated to Data table - Intelligence Community Design System