Search documentation v0.6.1

Data Table

Tables with filtering, sorting, pagination, and column toggle support

Source ↗️ Report Issue ↗️

Visualize and manage complex data in a clear, organized, and easily navigable way using the DataTable component. Data tables can be filtered, sorted, broken into pages, and they also support column toggle functionality. Entries supports the use of HTML markup.

Preview
ID Score Status
#1 47 suspended
#2 195 inactive
#3 177 inactive
#4 4 inactive
#5 145 active
#6 299 suspended
#7 150 active
#8 23 active
#9 92 active
#10 68 inactive
#11 121 inactive
#12 160 inactive
How to use DataTables in Astro
---
import { DataTable } from 'webcoreui/astro'
const data = [
['#1', '47', 'suspended'],
['#2', '195', 'inactive']
]
---
<DataTable
headings={['ID', 'Score', 'Status']}
data={data}
itemsPerPage={5}
/>
How to use DataTables in Svelte
<script>
import { DataTable } from 'webcoreui/svelte'
const data = [
['#1', '47', 'suspended'],
['#2', '195', 'inactive']
]
</script>
<DataTable
headings={['ID', 'Score', 'Status']}
data={data}
itemsPerPage={5}
/>
How to use DataTables in React
import React from 'react'
import { DataTable } from 'webcoreui/react'
const data = [
['#1', '47', 'suspended'],
['#2', '195', 'inactive']
]
const Component = () => (
<DataTable
headings={['ID', 'Score', 'Status']}
data={data}
itemsPerPage={5}
/>
)
export default Component

The API of the DataTable component matches the API of the Table component, meaning you can use any Table component specific prop on your DataTable components as well. To create the table, you must pass a data prop that references a multidimensional array of strings, where each array corresponds with a row. Strings can also include HTML markup.

Tip
Visit the documentation of the Table component to see what table-specific props can be used with the DataTable component.

To add pagination to this table, we can specify the itemsPerPage prop that sets the number of rows on a given page. If the number specified in the itemsPerPage prop is less than the total number of rows, the DataTable component will automatically add the pagination functionality.

Custom Pagination

The pagination can be customized using the pagination prop. For example, to add page number, we can modify the pagination prop in the following way:

ID Score Status
#1 47 suspended
#2 195 inactive
#3 177 inactive
#4 4 inactive
#5 145 active
#6 299 suspended
#7 150 active
#8 23 active
#9 92 active
#10 68 inactive
#11 121 inactive
#12 160 inactive
<DataTable
headings={['ID', 'Score', 'Status']}
data={data}
itemsPerPage={5}
pagination={{
showChevrons: true,
pages: [
{ label: 1, active: true },
{ label: 2 },
{ label: 3 }
]
}}
/>

To see all possible options for the pagination prop, see the API documentation of the Pagination component.

Filtering

To enable filtering for the DataTable component, you can mark a column as filterable by defining a heading as a HeadingObject instead of a string, and setting its filterable property to true:

ID Score Status
#1 47 suspended
#2 195 inactive
#3 177 inactive
#4 4 inactive
#5 145 active
#6 299 suspended
#7 150 active
#8 23 active
#9 92 active
#10 68 inactive
#11 121 inactive
#12 160 inactive
<DataTable
headings={[{ name: 'ID', filterable: true }, 'Score', 'Status']}
data={data}
itemsPerPage={5}
/>

This will make the ID column only filterable. Try to filter for one of the IDs. Filtering for scores or statuses will yield no result as they’re not filterable. The filter input will only be displayed if one of the headings is marked as filterable using the filterable property.

In case you don’t need special behavior for a column, simply specify the heading as a string. A HeadingObject can have the following properties:

Filter Event

To listen to filter events, you can listen to the dataTableFilter event in Astro, or use the onFilter prop for Svelte and React components:

ID Score Status
#1 47 suspended
#2 195 inactive
#3 177 inactive
#4 4 inactive
#5 145 active
#6 299 suspended
#7 150 active
#8 23 active
#9 92 active
#10 68 inactive
#11 121 inactive
#12 160 inactive
First result: N/A (12 results)
---
import { DataTable } from 'webcoreui/astro'
const data = [ ... ]
const results = data.length
const firstResult = 'N/A'
---
<DataTable
headings={[{ name: 'ID', filterable: true }, 'Score', 'Status']}
data={data}
itemsPerPage={5}
/>
<pre>First result: {firstResult} ({results} results)</pre>
<script>
import { listen } from 'webcoreui'
const pre = document.querySelector('pre') as HTMLPreElement
listen('dataTableFilter', event => {
const results = event.numberOfResults
const firstResult = event.results[0].innerText.split('\t')
pre.innerText = `First result: ${firstResult} (${results} results)`
})
</script>
<script>
import { DataTable } from 'webcoreui/svelte'
const data = [ ... ]
let results = data.length
let firstResult = 'N/A'
const filter = event => {
results = event.numberOfResults
firstResult = JSON.stringify(event.results[0])
}
</script>
<DataTable
headings={[{ name: 'ID', filterable: true }, 'Score', 'Status']}
data={data}
itemsPerPage={5}
onFilter={filter}
/>
<pre>First result: {firstResult} ({results} results)</pre>
import React, { useState } from 'react'
import { DataTable } from 'webcoreui/react'
const data = [ ... ]
const Component = () => {
const [results, setResults] = useState(data.length)
const [firstResult, setFirstResult] = useState('N/A')
const filter = event => {
setResults(event.numberOfResults)
setFirstResult(JSON.stringify(event.results[0]))
}
return (
<React.Fragment>
<DataTable
headings={[{ name: 'ID', filterable: true }, 'Score', 'Status']}
data={data}
itemsPerPage={5}
onFilter={filter}
/>
<pre>First result: {firstResult} ({results} results)</pre>
</React.Fragment>
)
}
export default Component

Customized Filtering

The filtering functionality can further be customized by using the following three props on the DataTable component:

ID Score Status
#1 47 suspended
#2 195 inactive
#3 177 inactive
#4 4 inactive
#5 145 active
#6 299 suspended
#7 150 active
#8 23 active
#9 92 active
#10 68 inactive
#11 121 inactive
#12 160 inactive
<DataTable
headings={[{ name: 'ID', filterable: true }, 'Score', 'Status']}
data={data}
itemsPerPage={5}
filterPlaceholder="Search the database"
showFilterIcon={true}
noResultsLabel="No entries found..."
client:visible
/>

Sorting

Sorting can be enabled in a similar way as filtering. Set the sorting property of a HeadingObject to true to add sorting option to a column:

#1 47 suspended
#2 195 inactive
#3 177 inactive
#4 4 inactive
#5 145 active
#6 299 suspended
#7 150 active
#8 23 active
#9 92 active
#10 68 inactive
#11 121 inactive
#12 160 inactive
<DataTable
headings={[
{
name: 'ID',
filterable: true,
sortable: true
}, {
name: 'Score',
sortable: true
}, {
name: 'Status',
sortable: true
}]}
data={data}
itemsPerPage={5}
/>

When sorting is enabled, a sort icon will appear next to the column’s name to indicate that the column can be sorted.

Column Toggles

Last but not least, a heading can also has a toggleable property. Once one of the headings are set as toggleable, a new field will appear next to the filter input to let users toggle the column on/off.

  • Score
  • Status
#1 47 suspended
#2 195 inactive
#3 177 inactive
#4 4 inactive
#5 145 active
#6 299 suspended
#7 150 active
#8 23 active
#9 92 active
#10 68 inactive
#11 121 inactive
#12 160 inactive
<DataTable
headings={[
{
name: 'ID',
filterable: true,
sortable: true
}, {
name: 'Score',
sortable: true,
toggleable: true
}, {
name: 'Status',
sortable: true,
toggleable: true
}]}
data={data}
itemsPerPage={5}
/>

Toggling columns will remove any active filtering. The label of the toggle columns input can also be modified using the columnToggleLabel prop:

  • Score
  • Status
#1 47 suspended
#2 195 inactive
#3 177 inactive
#4 4 inactive
#5 145 active
#6 299 suspended
#7 150 active
#8 23 active
#9 92 active
#10 68 inactive
#11 121 inactive
#12 160 inactive
<DataTable
headings={[ ... ]}
data={data}
columnToggleLabel="Toggle info"
itemsPerPage={5}
/>

Additional Label

Additional label can be displayed next to the pagination of the DataTable component using the subText prop:

  • Score
  • Status
#1 47 suspended
#2 195 inactive
#3 177 inactive
#4 4 inactive
#5 145 active
#6 299 suspended
#7 150 active
#8 23 active
#9 92 active
#10 68 inactive
#11 121 inactive
#12 160 inactive
<DataTable
headings={[ ... ]}
data={data}
subText={`Currently, there are ${data.length} total entries`}
itemsPerPage={5}
/>

API

type DataTableEventType = {
results: string[][]
numberOfResults: number
}
type HeadingObject = {
name: string
sortable?: boolean
toggleable?: boolean
filterable?: boolean
}
type DataTableProps = {
headings?: (HeadingObject | string)[]
filterPlaceholder?: string
showFilterIcon?: boolean
noResultsLabel?: string
itemsPerPage?: number | null
subText?: string
columnToggleLabel?: string
pagination?: PaginationProps
data: string[][]
hover?: boolean
striped?: 'column' | 'row' | null
offsetStripe?: boolean
compact?: boolean
maxHeight?: string
className?: string
id?: string
}
type SvelteDataTableProps = {
onFilter?: (event: DataTableEventType) => void
} & DataTableProps
type ReactDataTableProps = {
onFilter?: (event: DataTableEventType) => void
} & DataTableProps
See the documentation of the Pagination component for the PaginationProps type for the pagination prop.
PropPurpose
headings Sets headings for the columns. If the headings prop is not specified, filtering, sorting, and column toggle functionality will be disabled.
filterPlaceholder Sets the placeholder for the filter input. Defaults to "Filter entries".
showFilterIcon Shows a search icon in the filter input. Defaults to false.
noResultsLabel Sets the label that is shown when no results are found after overfiltering. Defaults to "No results.".
itemsPerPage Sets the number of rows per page.
subText Sets an additional label under the data table.
columnToggleLabel Sets the label for the column toggle button. Defaults to "Columns".
pagination Customize the pagination of the data table. It can accept the props of the Pagination component.
data Sets the table cells. Must be a multidimensional array of strings.
hover Adds a hover effect for rows. Defaults to false.
striped Adds stripes for the rows/columns. Its value can be one of column, or row.
offsetStripe Offsets the starting position of stripes if the striped prop is set.
compact Sets the padding of the cells to a smaller size.
maxHeight Sets a maximum height for the table, making it scrollable with a fixed header.
className Pass additional CSS classes for the data table.
id Pass an ID for the data table.
Svelte & React PropPurpose
onFilter Attach event listeners that are triggered when the data table is filtered.

Request improvement for this page