Data table

CANARY

Component demo

Interactive example

Web component

React

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

<IcDataTablecaption="Basic"columns={columns}data={data}/>

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 Attribute	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 is`false` . type: boolean	false
Property data Attribute	The row content for the table. type: IcDataTableDataType[]
Property density Attribute density	Set the density of the table including font and padding. type: IcDataTableDensityOptions - "default" \| "dense" \| "spacious"	"default"
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 the`variableRowHeight` method. type: IcDataTableRowHeights - "auto" \| number	"auto"
Property height Attribute height	Sets the table height. Can be set to`auto` or a specific value in`px` ,`rem` , or`%` . type: string
Property hideColumnHeaders Attribute hide-column-headers	If`true` , column headers will not be visible. type: boolean	false
Property loading Attribute loading	When set to`true` , the full table will show a loading state, featuring a radial indicator. type: boolean	false
Property loadingOptions Attribute	Sets the props for the circular loading indicator used in the loading state. type: { appearance?: IcThemeForegroundNoDefault; description?: string; label?: string; labelDuration?: number; max?: number; min?: number; progress?: number; showBackground?: boolean; monochrome?: boolean; } - { appearance?: IcThemeForegroundNoDefault; description?: string; label?: string; labelDuration?: number; max?: number; min?: number; progress?: number; showBackground?: boolean; monochrome?: boolean; }
Property maxWidth Attribute max-width	Sets the maximum width of the data table. Can be set in`px` ,`rem` , or`%` . type: string
Property minWidth Attribute min-width	Sets the minimum width of the data table. Can be set in`px` ,`rem` , or`%` . type: string
Property minimumLoadingDisplayDuration Attribute minimum-loading-display-duration	The minimum amount of time the`loading` state displays for before showing the data. Used to prevent flashing in the component. type: number	1000
Property paginationBarOptions Attribute	Sets the props for the built-in pagination bar. If the`pagination-bar` slot is used then this prop is ignored. type: IcPaginationBarOptions	{ itemsPerPageOptions: [ { label: "10", value: "10" }, { label: "25", value: "25" }, { label: "50", value: "50" }, ], rangeLabelType: "page", type: "simple", showItemsPerPageControl: true, showGoToPageControl: true, alignment: "right", itemLabel: "Item", pageLabel: "Page", hideRangeLabel: false, hideAllFromItemsPerPage: false, theme: "inherit", monochrome: false, }
Property showPagination Attribute show-pagination	If`true` , adds a pagination bar to the bottom of the table. type: boolean	false
Property sortOptions Attribute	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; }	{ sortOrders: ["unsorted", "ascending", "descending"], defaultColumn: "", }
Property sortable Attribute sortable	If`true` , allows table columns to be sorted using applied sort buttons. type: boolean	false
Property stickyColumnHeaders Attribute sticky-column-headers	If`true` , column headers will remain at the top of the table when scrolling vertically. type: boolean	false
Property stickyRowHeaders Attribute sticky-row-headers	If`true` , 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"	"fixed"
Property truncationPattern Attribute truncation-pattern	Sets the method used to truncate long text in cells where textWrap is`false` . The`tooltip` truncation pattern allows the overflowing text to be seen in a tooltip. The`show-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"
Property updating Attribute updating	If`true` , the table displays a linear loading indicator below the header row to indicate an updating state. type: boolean	false
Property updatingOptions Attribute	Sets the props for the linear loading indicator used in the updating state. type: { appearance?: IcThemeForegroundNoDefault; description?: string; max?: number; min?: number; progress?: number; monochrome?: boolean; } - { appearance?: IcThemeForegroundNoDefault; description?: string; max?: number; min?: number; progress?: number; monochrome?: boolean; }
Property variableRowHeight Attribute	Allows for custom setting of row heights on individual rows based on an individual value from the`data` prop and the row index. If the function returns`null` , that row's height will be set to the`globalRowHeight` property. type: (params: { [key: string]: any; index: number; }) => IcDataTableRowHeights \| null - (params: { [key: string]: any; index: number; }) => IcDataTableRowHeights
Property width Attribute width	Sets the table width. Can be set to`auto` or a specific value in`px` ,`rem` , or`%` . type: string

Property

caption

Attribute

caption

The title for the table only visible to screen readers.

Required

type: string

Property

columns

Attribute

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

Attribute

The row content for the table.

type: IcDataTableDataType[]

Property

density

Attribute

density

Set the density of the table including font and padding.

type: IcDataTableDensityOptions - "default" | "dense" | "spacious"

Default: "default"

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

Property

hideColumnHeaders

Attribute

hide-column-headers

Iftrue , column headers will not be visible.

type: boolean

Default: false

Property

Attribute

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

type: boolean

Default: false

Property

loadingOptions

Attribute

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

type: { appearance?: IcThemeForegroundNoDefault; description?: string; label?: string; labelDuration?: number; max?: number; min?: number; progress?: number; showBackground?: boolean; monochrome?: boolean; } - { appearance?: IcThemeForegroundNoDefault; description?: string; label?: string; labelDuration?: number; max?: number; min?: number; progress?: number; showBackground?: boolean; monochrome?: boolean; }

Property

maxWidth

Attribute

max-width

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

type: string

Property

minWidth

Attribute

min-width

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

type: string

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

Attribute

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

type: IcPaginationBarOptions

Default: { itemsPerPageOptions: [ { label: "10", value: "10" }, { label: "25", value: "25" }, { label: "50", value: "50" }, ], rangeLabelType: "page", type: "simple", showItemsPerPageControl: true, showGoToPageControl: true, alignment: "right", itemLabel: "Item", pageLabel: "Page", hideRangeLabel: false, hideAllFromItemsPerPage: false, theme: "inherit", monochrome: false, }

Property

showPagination

Attribute

show-pagination

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

type: boolean

Default: false

Property

sortOptions

Attribute

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; }

Default: { sortOrders: ["unsorted", "ascending", "descending"], defaultColumn: "", }

Property

sortable

Attribute

sortable

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

type: boolean

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"

Default: "fixed"

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"

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

Attribute

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

type: { appearance?: IcThemeForegroundNoDefault; description?: string; max?: number; min?: number; progress?: number; monochrome?: boolean; } - { appearance?: IcThemeForegroundNoDefault; description?: string; max?: number; min?: number; progress?: number; monochrome?: boolean; }

Property

variableRowHeight

Attribute

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

Property

width

Attribute

width

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

type: string

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.

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.

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 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

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

Web component

React

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

<IcDataTable
caption="Embedded"
columns={columns}
data={data}
embedded
/>

Dense

Interactive example

Web component

React

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

<IcDataTable
caption="Dense"
columns={columns}
data={data}
density="dense"
/>

Spacious

Interactive example

Web component

React

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

<IcDataTable
caption="Spacious"
columns={columns}
data={data}
density="spacious"
/>

Sticky column headers

Interactive example

Web component

React

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

<IcDataTable
className={classes.dataTable}
caption="Sticky Column Headers"
columns={long_columns}
data={long_data}
stickyColumnHeaders
ref={dataTableEl}
/>

Row headers

Interactive example

Web component

React

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

<IcDataTable
caption="Row Headers"
columns={columns}
data={data}
/>

Sortable

Interactive example

Web component

React

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

<IcDataTable
caption="Sort"
columns={columns}
data={data}
sortable
onIcSortChange={(e)=>console.log("Sort changed", e.detail)}
/>

Sort options

Interactive example

Web component

React

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

<IcDataTable
caption="Sort Options"
columns={columns}
data={data}
sortable
sortOptions={{
    sortOrders:["descending","unsorted"],
    defaultColumn:"firstName",
}}
/>

Pagination

Interactive example

Web component

React

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

<IcDataTable
caption="Pagination"
columns={long_columns}
data={long_data}
showPagination
paginationOptions={{
    itemsPerPage:[
{ label:"5", value:"5"},
{ label:"10", value:"10"},
{ label:"15", value:"15"},
],
    itemsPerPageControl:true,
}}
/>

Column overrides

Interactive example

Web component

React

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

<IcDataTable
caption="Column overrides"
columns={columns}
data={data}
/>

Row overrides

Interactive example

Web component

React

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

<IcDataTable
caption="Row overrides"
columns={columns}
data={data}
/>

Cell overrides

Interactive example

Web component

React

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

<IcDataTable
caption="Cell overrides"
columns={columns}
data={data}
/>

Default Empty State

Interactive example

Web component

React

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

<IcDataTablecaption="Default Empty State"columns={columns}/>

Slotted Empty State

Interactive example

Data source error

Error loading new data

Web component

React

<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>

<IcDataTable
caption="Slotted Empty State"
columns={columns}
>
<IcEmptyStateslot="empty-state"aligned="left"heading="Data source error"body="Error loading new data">
<IcButtonslot="actions">Retry</IcButton>
</IcEmptyState>
</IcDataTable>

Loading state

Interactive example

Web component

React

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

<IcDataTable
caption="Loading state"
columns={columns}
data={data}
loading
/>

Updating state

Interactive example

Web component

React

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

<IcDataTable
caption="Updating state"
columns={columns}
data={data}
updating
updatingOptions={{ progress:30}}
/>

Links and Elements in data

Interactive example

Web component

React

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

<IcDataTable
caption="Links and Elements in data"
columns={columns}
data={data}
>
{data.map((_, index)=>(
<IcButton
key={index}
slot={`actions-${index}`}
variant="destructive"
onClick={()=> _.closest('Delete')}
>
      Delete
</IcButton>
))}
</IcDataTable>

Custom icons

Interactive example

Web component

React

<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>

<IcDataTablecaption="Custom icons"columns={columns}data={data}>
<SlottedSVGslot="age-column-icon"path={mdiCakeVariantOutline}/>
</IcDataTable>

Custom row heights

Interactive example

Web component

React

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

<IcDataTable
caption="Custom Row Heights"
columns={columns}
data={data}
globalRowHeight={80}
variableRowHeight={rowHeightFunc}
/>

Custom title bar

Interactive example

This is some text and this is an inline link within the text.

Web component

React

<ic-data-tableid="data-table"caption="Custom Title Bar">
<ic-data-table-title-bar
description="Data table description that describes the purpose of the table."
metadata="128 items | 32gb | Updated: 01/02/03"
>
<ic-buttonslot="primary-action">Primary</ic-button>
<ic-buttonslot="custom-actions"variant="icon"aria-label="Icon 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="Icon 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-buttonslot="custom-actions"variant="icon"aria-label="Icon 3">
<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>
        This is some text and{' '}
<ic-linkhref="#">this is an inline link</ic-link> within the text.
</p>
</ic-typography>
</ic-data-table-title-bar>
</ic-data-table>

<IcDataTablecaption="Custom Title Bar"columns={columns}data={data}>
<IcDataTableTitleBar
slot="title-bar"
description="Data table description that describes the purpose of the table."
metadata="128 items | 32gb | Updated: 01/02/03"
>
<IcButtonslot="primary-action">Primary</IcButton>
<IcButtonslot="custom-actions"variant="icon"aria-label="Icon 1">
<SlottedSVGpath={mdiImage}viewBox="0 0 24 24"/>
</IcButton>
<IcButtonslot="custom-actions"variant="icon"aria-label="Icon 2">
<SlottedSVGpath={mdiImage}viewBox="0 0 24 24"/>
</IcButton>
<IcButtonslot="custom-actions"variant="icon"aria-label="Icon 3">
<SlottedSVGpath={mdiImage}viewBox="0 0 24 24"/>
</IcButton>
<IcTypographyslot="description"variant="body">
<p>
        This is some text and{' '}
<IcLinkhref="#">this is an inline link</IcLink> within the text.
</p>
</IcTypography>
</IcDataTableTitleBar>
</IcDataTable>

Interactive example

Web component

React

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

<IcDataTablecaption="Data table truncation - tooltip"columns={columns}data={data}truncationPattern="tooltip"globalRowHeight={40}/>

Truncation - show/hide

Interactive example

Web component

React

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

<IcDataTablecaption="Data table truncation - show/hide"columns={columns}data={data}truncationPattern="show-hide"globalRowHeight={40}/>

Text wrap

Interactive example

Web component

React

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

<IcDataTablecaption="Data table text wrap"columns={columns}data={data}globalRowHeight={40}/>

Last reviewed 21 August 2024 .

Component demo

Interactive example

Data table details

Props

Slots

Events

Methods

Variants

Embedded

Interactive example

Dense

Interactive example

Spacious

Interactive example

Sticky column headers

Interactive example

Row headers

Interactive example

Sortable

Interactive example

Sort options

Interactive example

Pagination

Interactive example

Column overrides

Interactive example

Row overrides

Interactive example

Cell overrides

Interactive example

Default Empty State

Interactive example

Slotted Empty State

Interactive example

Loading state

Interactive example

Updating state

Interactive example

Links and Elements in data

Interactive example

Custom icons

Interactive example

Custom row heights

Interactive example

Custom title bar

Interactive example

Truncation - tooltip

Interactive example

Truncation - show/hide

Interactive example

Text wrap

Interactive example