KTable link to current page

develop | Release notes

Overview
#

The KTable component is an accessible and customizable table component designed to handle a variety of data presentation needs. The component is suitable for both simple and complex data tables. It offers:

  • Offers built-in sorting by default
  • Integrates with already sorted data
  • Keyboard navigation
  • Dynamic column resizing
  • Sticky headers

Usage
#

Table without sorting functionality

This is an example to show how KTable can be used without any sorting functionality, as a simple table. 


      <KTable
        :headers="headers"
        :rows="rows"
        caption="Non Sortable Table"
      />
    

      data() {
        return {
          headers: [
            { label: 'Name', dataType: 'string', columnId: 'name' },
            { label: 'Age', dataType: 'number', columnId: 'age' },
            { label: 'City', dataType: 'string', columnId: 'city' },
          ],
          rows: [
              ['John Doe', 28, 'New York'],
              ['Jane Smith', 34, 'Los Angeles'],
              ['Samuel Green', 22, 'Chicago'],
              ['Alice Johnson', 30, 'Houston'],
              ['Michael Brown', 45, 'Phoenix'],
              ['Emily Davis', 27, 'Philadelphia'],
            ]
          };
      },
Non-sortable table
Name Age City
John Doe 28 New York
Jane Smith 34 Los Angeles
Samuel Green 22 Chicago
Alice Johnson 30 Houston
Michael Brown 45 Phoenix
Emily Davis 27 Philadelphia

Table with sorting

The KTable offers built-in sorting functionality. There are 4 permissible data types - string,number,date and undefined. Columns declared with undefined data type are not sortable. This example demonstrates a table with sorting enabled via the sortable prop.

Clicking the same header multiple times toggles the sort direction cyclically in the order of ascending, descending, and unsorted. 


      <KTable
        :headers="headers"
        :rows="rows"
        caption="Table with built-in sorting"
        sortable
      />
    

      data() {
        return {
          headers: [
            { label: 'Name', dataType: 'string', columnId: 'name' },
            { label: 'Age', dataType: 'number', columnId: 'age' },
            { label: 'City', dataType: 'string', columnId: 'city' },
          ],
          rows: [
            ['John Doe', 28, 'New York'],
            ['Jane Smith', 34, 'Los Angeles'],
            ['Samuel Green', 22, 'Chicago'],
            ['Alice Johnson', 30, 'Houston'],
            ['Michael Brown', 45, 'Phoenix'],
            ['Emily Davis', 27, 'Philadelphia'],
          ]
        };
      },
In-Built Sorting Table
Name Age City
John Doe 28 New York
Jane Smith 34 Los Angeles
Samuel Green 22 Chicago
Alice Johnson 30 Houston
Michael Brown 45 Phoenix
Emily Davis 27 Philadelphia

Table showing use of slots

This is an example to show how slots can be used in KTable. The table currently provides slots for header and cell which can be used to customize the table header and cell content respectively. 


      <KTable
        :headers="slotHeaders"
        :rows="slotRows"
        caption="Table showing use of slots"
        sortable
      >
        <template #header="{ header, colindex }">
          <span>{ header.label } (Local)</span>
        </template>
        <template #cell="{ content, rowIndex, colIndex }">
          <span v-if="colIndex === 1">{ content } years old</span>
          <span v-else-if="colIndex === 4"><KButton>Test</KButton></span>
          <span v-else>{ content }</span>
        </template>
      </KTable>
    

      data() {
        return {
          slotHeaders: [
            { label: 'Name', dataType: 'string', columnId: 'name' },
            { label: 'Age', dataType: 'number', columnId: 'age' },
            { label: 'City', dataType: 'string', columnId: 'city' },
            { label: 'Joined', dataType: 'date', columnId: 'joined' },
            { label: 'Misc', dataType: 'undefined', columnId: 'misc' },
          ],
          slotRows: [
            ['John Doe', 28, 'New York', '2022-01-15T00:00:00Z', 'N/A'],
            ['Jane Smith', 34, 'Los Angeles', '2021-12-22T00:00:00Z', 'N/A'],
            ['Samuel Green', 22, 'Chicago', '2023-03-10T00:00:00Z', 'N/A'],
            ['Alice Johnson', 30, 'Houston', '2020-07-18T00:00:00Z', 'N/A'],
          ],
        };
      },
Table showing use of slots
Name (Local) Age (Local) City (Local) Joined (Local) Misc (Local)
John Doe28 years oldNew York2022-01-15T00:00:00Z
Jane Smith34 years oldLos Angeles2021-12-22T00:00:00Z
Samuel Green22 years oldChicago2023-03-10T00:00:00Z
Alice Johnson30 years oldHouston2020-07-18T00:00:00Z

Table with custom column widths

This is an example to show how KTable can be used with custom column widths. The column widths are defined in the headers prop. The width property is used to define the overall width of the column. The minWidth defines the minimum width of column, below which the column will not shrink. 


      <KTable
        :headers="headersWithCustomWidths"
        :rows="customRows"
        caption="Table showing columns with custom widths"
        sortable
      />
    

      data() {
        return {
          headersWithCustomWidths: [
            { label: 'Name', dataType: 'string', minWidth: '20px', width: '2%', columnId: 'name' },
            { label: 'Age', dataType: 'number', minWidth: '100px', width: '33%', columnId: 'age' },
            { label: 'City', dataType: 'string', minWidth: '200px', width: '25%', columnId: 'city' },
            {
              label: 'Joined',
              dataType: 'date',
              minWidth: '150px',
              width: '20%',
              columnId: 'joined',
            },
            {
              label: 'Misc',
              dataType: 'undefined',
              minWidth: '100px',
              width: '20%',
              columnId: 'misc',
            },
          ],
          customRows: [
            ['John Doe', 28, 'New York', '2022-01-15T00:00:00Z', 'N/A'],
            ['Jane Smith', 34, 'Los Angeles', '2021-12-22T00:00:00Z', 'N/A'],
            ['Samuel Green', 22, 'Chicago', '2023-03-10T00:00:00Z', 'N/A'],
            ['Alice Johnson', 30, 'Houston', '2020-07-18T00:00:00Z', 'N/A'],
          ],
        };
      },
Table showing columns with custom widths
Name Age City Joined Misc
John Doe 28 New York 2022-01-15T00:00:00Z N/A
Jane Smith 34 Los Angeles 2021-12-22T00:00:00Z N/A
Samuel Green 22 Chicago 2023-03-10T00:00:00Z N/A
Alice Johnson 30 Houston 2020-07-18T00:00:00Z N/A

Table with default sort

This is an example to show how to use the defaultSort prop to sort the table based on a particular column upon the initial load. The defaultSort attribute can be used irrespective of the sortable attribute.

The defaultSort attribute takes an object with two properties - columnId and direction. The columnId is the unique identifier of the column based on which the table should be sorted. The direction can be either asc or desc.

To make use of defaultSort, please ensure that the disableBuiltinSorting attribute is not set to true. 


      <h4>Sortable table with rows sorted by 'Age' column</h4>
      <KTable
        :headers="headers"
        :rows="rows"
        caption="Sortable Table with Rows Sorted by 'Age' Column"
        sortable
        :defaultSort="{ columnId: 'age', direction: 'asc' }"
      />

      <h4>Unsortable table with rows sorted by 'Age' column</h4>
      <KTable
        :headers="headers"
        :rows="rows"
        caption="Unsortable Table with Rows Sorted by 'Age' Column"
        :defaultSort="{ columnId: 'age', direction: 'asc' }"
      />
    

      data() {
        return {
          headers: [
            { label: 'Name', dataType: 'string', columnId: 'name' },
            { label: 'Age', dataType: 'number', columnId: 'age' },
            { label: 'City', dataType: 'string', columnId: 'city' },
          ],
          rows: [
            ['John Doe', 28, 'New York'],
            ['Jane Smith', 34, 'Los Angeles'],
            ['Samuel Green', 22, 'Chicago'],
            ['Alice Johnson', 30, 'Houston'],
            ['Michael Brown', 45, 'Phoenix'],
            ['Emily Davis', 27, 'Philadelphia'],
          ]
        };
      },

Sortable Table with Rows Sorted by 'Age' Column

Sortable Table with Rows Sorted by 'Age' Column
Name Age City
Samuel Green 22 Chicago
Emily Davis 27 Philadelphia
John Doe 28 New York
Alice Johnson 30 Houston
Jane Smith 34 Los Angeles
Michael Brown 45 Phoenix

Unsortable Table with Rows Sorted by 'Age' Column

Unsortable Table with Rows Sorted by 'Age' Column
Name Age City
Samuel Green 22 Chicago
Emily Davis 27 Philadelphia
John Doe 28 New York
Alice Johnson 30 Houston
Jane Smith 34 Los Angeles
Michael Brown 45 Phoenix

Disable built-in sorting

For sortable tables, you can use the disableBuiltinSorting prop to disable built-in sort function. This is useful when the table receives already sorted data, for example when sorting is done by backend or a custom sorting function outside the table. In this case, when one of the header sort buttons is clicked, the table won't sort the column itself, but only emit the changeSort event to notify the parent component to handle the sorting logic. The event contains column index of the header and the sort order in its payload.

You should not use this attribute if sortable is set to false. If sortable is set to true, then the table component will emit a changeSort event with column index of the header clicked and the sort order to notify the parent component to handle the sorting logic. 


      <KTable
        :headers="headers"
        :rows="rows"
        caption="Disable Builtin Sorting Example"
        sortable
        disableDefaultSorting
        @changeSort="changeSortHandler"
      />
    

      data() {
        return {
          headers: [
            { label: 'Name', dataType: 'string', columnId: 'name' },
            { label: 'Age', dataType: 'number', columnId: 'age' },
            { label: 'City', dataType: 'string', columnId: 'city' },
          ],
          rows: [
            ['John Doe', 28, 'New York'],
            ['Jane Smith', 34, 'Los Angeles'],
            ['Samuel Green', 22, 'Chicago'],
            ['Alice Johnson', 30, 'Houston'],
            ['Michael Brown', 45, 'Phoenix'],
            ['Emily Davis', 27, 'Philadelphia'],
          ]
        };
      },
      methods: {
        changeSortHandler(index, sortOrder) {
          console.log(`changeSort event emitted with index: ${index} and sortOrder: ${sortOrder}`);
        },
      },
Disable Builtin Sorting Example
Name Age City
John Doe 28 New York
Jane Smith 34 Los Angeles
Samuel Green 22 Chicago
Alice Johnson 30 Houston
Michael Brown 45 Phoenix
Emily Davis 27 Philadelphia

Props
#

Name Description Type Default Required
headers
#
An array of objects: { label, dataType, minWidth, width, columnId } representing the headers of the table. The dataType can be one of 'string', 'number', 'date', or 'undefined'. label and dataType are required. minWidth and width are optional. columnId is an unique identifier for the column, and can be a number or a string.
 array — true
rows
#
An array of arrays representing the rows of the table. Each row should have the same number of elements as the headers array.
 array — true
caption
#
The caption of the table
 string — true
sortable
#
Enables or disables sorting functionality for the table headers.
 boolean false —
emptyMessage
#
The message to display when the table is empty.
 string 'No data available' —
dataLoading
#
Indicates whether the data is currently being loaded.
 boolean false —
defaultSort
#
Indicates whether the table is to be sorted by default by any header or not. By default it is an empty object which means no default sorting is to be used. It accepts a configuration object { columnId, direction }. columnId references a columnId defined for a header in headers. This specifies a column by which the table should be sorted when initially loaded. direction can be 'asc' for ascending or 'desc' for descending sort direction.
 object {} —
disableBuiltinSorting
#
Disables built-in sort function. This is useful when you want to define your own sorting logic. Refer to the examples above for more details.
 boolean false —

Slots
#

Name Description
header
#
Scoped slot for customizing the content of each header cell.
cell
#
Scoped slot for customizing the content of each data cell.