Kongponents

# Table

Pass a fetcher function to build a slot-able table.

  <KTable :fetcher="fetcher" :headers="headers" />

Note

The KTable component requires the @vue/composition-api package as a peerDependency. You must manually add the package to your host project by running the following

yarn add @vue/composition-api

When importing KTable into your project, you will likely need to explicity import the vue file as shown below

import KTable from '@kongponents/ktable/KTable.vue'

NOTE

KTable implements KIcon which imports .svg files directly, so a loader is needed in order to render these in your application such as the webpack raw-loader. See here for more information.

# Props

# hasHover

Highlight the table row on hover. By default this is set to true. In the example we can set it to false as well.

<template>
  <KTable
    :fetcher="fetcher"
    :headers="headers"
    :hasHover="false" />
</template>

# hasSideBorder

Adds left border to each table row. By default set to false. The colors can be overridden by themes. The below example demonstrates the disabled state:

<template>
  <KTable
    :fetcher="fetcher"
    :headers="headers"
    :hasSideBorder="true" />
</template>

# hasError

See the State section about hasError

# isLoading

See the State section about isLoading

# disablePaginationPageJump

Set this to true to limit pagination navigation to previous / next page only.

<template>
  <KTable
    :fetcher="fetcher"
    :headers="headers"
    :disablePaginationPageJump="true" />
</template>

# disablePagination

Set this to true to remove the pagination bar when using a fetcher.

# disableSorting

Set this to true to disable ablity to sort.

# enableClientSort

Experimental - set this prop to true to enable client side sorting if using a fetcher that returns unpaginatinated data. This functionality may be flaky.

# sortHandlerFn

Use a custom sort handler function to handle sorting table data for specific columns

Notes

  1. In order for a column to use the custom sort handler function, useSortHandlerFn must be set to true in the headers object

  2. Sort handler functions can take four params:

  • key: the key of the column to be sorted
  • prevKey: the key of the column previously sorted
  • sortColumnOrder: the order in which to sort the column (asc or desc)
  • data: the data returned from the fetcher function response

# sortHandlerFn Example

Here the last_seen column is set to use the custom sort handler function via the useSortHandlerFn property set in the table header object. The function passed into the sortHandlerFn prop sorts and returns the table data. The other columns use the default built-in client side sort function because the useSortHandlerFn property is not set in the header objects.

<template>
  <KTable
    :fetcher="fetcher"
    :headers="headers"
    :sortHandlerFn="sortHandlerFn"
    enable-client-sort
  />
</template>

<script>
export default {
  data () {
    return {
      headers: [
        { label: 'Host', key: 'hostname', sortable: true },
        { label: 'Version', key: 'version', sortable: true },
        { label: 'Connected', key: 'connected', sortable: true },
        { label: 'Last Seen', key: 'last_seen', sortable: true, useSortHandlerFn: true }
      ],
    }
  },
  methods: {
    sortHandlerFn({ key, prevKey, sortColumnOrder, data}) {
      return data.sort((a, b) => {
        if (key === 'last_seen') {
          if (sortColumnOrder === 'asc') {
            if (a.last_ping > b.last_ping) {
              return 1
            } else if (a.last_ping < b.last_ping) {
              return -1
            }

            return 0
          } else {
            if (a.last_ping > b.last_ping) {
              return -1
            } else if (a.last_ping < b.last_ping) {
              return 1
            }

            return 0
          }
        }
      })
    },

    fetcher() {
      return {
        data: [
          {
            id: '08cc7d81-a9d8-4ae1-a42f-8d4e5a919d07',
            version: '2.8.0.0-enterprise-edition',
            hostname: '99e591ae3776',
            last_ping: 1648855072,
            connected: 'Disconnected',
            last_seen: '6 days ago'
          },
          {
            id: '08cc7d81-a9d8-4ae1-a42f-8d4e5a919d07',
            version: '2.7.0.0-enterprise-edition',
            hostname: '19e591ae3776',
            last_ping: 1649362660,
            connected: 'Connected',
            last_seen: '3 hours ago',
          },
          {
            id: '08cc7d81-a9d8-4ae1-a42f-8d4e5a919d07',
            version: '2.8.1.0-enterprise-edition',
            hostname: '79e591ae3776',
            last_ping: 1649355460,
            connected: 'Connected',
            last_seen: '5 hours ago',
          },
          {
            id: '08cc7d81-a9d8-4ae1-a42f-8d4e5a919d07',
            version: '2.6.0.0-enterprise-edition',
            hostname: '89e591ae3776',
            last_ping: 1648155072,
            connected: 'Disconnected',
            last_seen: '14 days ago'
          },
          {
            id: '08cc7d81-a9d8-4ae1-a42f-8d4e5a919d07',
            version: '2.8.2.0-enterprise-edition',
            hostname: '59e591ae3776',
            last_ping: 1649855072,
            connected: 'Connected',
            last_seen: 'Just now'
          },
        ]
      }
    },
  }
}
</script>

# fetcher

Use a custom fetcher function to fetch table data and leverage server-side search, sort and pagination.

Note

All fetcher functions should take a single param. This parameter is a JSON object supporting the following properties:

  • Pagination support:
    • page: the currently visible page - starts at 1
    • pageSize: the number of items to display per page
  • Sort support:
    • sortColumnKey: the column to sort by's key defined in the headers prop
    • sortColumnOrder: can be 'asc' or 'desc'
  • Search support:
    • query: a text string to filter table data on

Note

All fetcher functions should return a JSON object. This JSON object should contain the following properties:

  • total - the total count of items (if using pagination)
  • data - an array of JSON objects to populate the table with

Example fetcher function:

fetcher(payload) {
  const params = {
    _limit: payload.pageSize,
    _page: payload.page
  }

  if (query) {
    params.q = payload.query
    params._page = 1
  }

  if (sortKey) {
    params._sort = payload.sortColumnKey
    params._order = payload.sortColumnOrder
  }

  return axios.get('/user_list', {
    baseURL: 'https://kongponents.dev/api',
    params
  }).then(res => {
    return {
      total: res.total,
      data: res.data
    }
  })
}

The fetcher function does not actually need to make an API call. Tables that can get their data synchronously can be modified to use a fetcher that returns the static data object.

Note

Remember that the fetcher function is responsible for managing pagination/sort/search. So if returning a static data object these features should be explicitly disabled.

<template>
  <KTable
    :fetcher="() => {
      return {
        data: [
          {
            name: 'Basic Auth',
            id: '517526354743085',
            enabled: 'true'
          },
          {
            name: 'Website Desktop',
            id: '328027447731198',
            enabled: 'false'
          },
          {
            name: 'Android App',
            id: '405383051040955',
            enabled: 'true'
          }
        ]
      }
    }"
    :initial-fetcher-params="{
      sortColumnKey: 'name',
      sortColumnOrder: 'asc'
    }"
    :headers="[
      { label: 'Name', key: 'name', sortable: true },
      { label: 'Id', key: 'id', sortable: true },
      { label: 'Enabled', key: 'enabled', sortable: false }
    ]"
    disablePagination
    :enableClientSort="true"
  />
</template>

# fetcherCacheKey

The fetcher functionality makes use of SWRV to handle caching of response data. Whenever the cache key is changed the fetcher will automatically refire and repopulate the table data.

<template>
  <KTable
    :fetcher="fetcher"
    :headers="headers"
    :fetcherCacheKey="cacheKey" />
</template>

<script>
export default {
  data () {
    return {
      cacheKey: 1
    }
  },
  methods: {
    itemDeleted () {
      // take an action on the DOM
      cacheKey++ // triggers refetch
    }
  }
}
</script>

# searchInput

Pass in a string of search input for server-side table filtering. See the Server-side function section for an example.

# headers

Pass in an array of header objects for the table.

Parameter Type Description
key string A unique key for the column
label string The label displayed on the table for the column
sortable boolean Enables or disables server-side sorting for the column (false by default)
hideLabel boolean Hides or displays the column label (useful for actions columns)
useSortHandlerFn boolean Uses the function passed in the sortHandlerFn prop to sort the column data instead of the default client sorter function

Note

sortable columns emit a sort event when clicked, returns:

{
  prevKey,        // the previously sorted column
  sortColumnKey,  // the column being sorted now
  sortColumnOrder // the sort direction (asc/desc)
}

Example headers array:

<script>
  export default {
    data() {
      return {
        headers: [
          { key: 'name', label: 'Name', sortable: true },
          { key: 'email', label: 'Email', sortable: true },
          { key: 'department', label: 'department', sortable: true },
          { key: 'start_date', label: 'Start Date', sortable: true },
          { key: 'actions', label: '', sortable: false, hideLabel: true },
        ]
      }
    }
  }
</script>

# initialFetcherParams

Pass in an object of parameters for the initial fetcher function call. If not provided, will default to the following values:

{ pageSize: 15, page: 1, query: '', sortColumnKey: '', sortColumnOrder: '' }

# paginationTotalItems

Pass the total number of items in the set to populate the pagination text:

1 to 20 of <paginationTotalItems>

If not provided the fetcher response should return a top-level property total or return a data property that is an array.

# paginationNeighbors

Pass in a number of pagination neighbors to be used by the pagination component. See more detail in the Pagination docs.

# paginationPageSizes

Pass in an array of page sizes for the page size dropdown. If not provided will default to the following:

[15, 30, 50, 75, 100]

# Row Attributes

A prop to add custom properties to individual rows. The row object is passed as a param.

rowAttrs - This prop takes a function that returns an object comprising the attributes.

<template>
  <KTable
    :fetcher="fetcher"
    :headers="headers"
    :rowAttrs="rowAttrsFn" />
</template>

<script>
export default {
  methods: {
    rowAttrsFn (rowItem) {
      return {
        class: {
          'enabled': rowItem.enabled === 'true',
          'disabled': rowItem.enabled === 'false'
        },
        'data-testid': 'row-item'
      }
    }
  }
}
</script>

<style>
.k-table {
  tr.enabled {
    --KTableHover: var(--green-200, #ccffe1);
    --KTableBorder: var(--green-400, #19a654);
  }

  tr.disabled {
    --KTableHover: var(--yellow-100, #fff9e6);
    --KTableBorder: var(--yellow-200, #ffdc73);
  }
}
</style>

# Cell Attributes

A prop to add custom properties to individual table cells or groups of cells. The cell attributes object is passed as a param.

cellAttrs - This prop takes a function that returns an object comprising the attributes.

Parameter Description
headerKey The header key of the column containing the cell
row The contents of the row containing the cell
rowIndex The zero-based index of the row containing the cell
colIndex The zero-based index of the cell within a row
<template>
  <KTable
    :fetcher="fetcher"
    :headers="headers"
    :cellAttrs="cellAttrsFn" />
</template>
<script>
export default {
  methods: {
    cellAttrsFn ({ headerKey, row, rowIndex, colIndex }) {
      /**
       * Sets cell background color based on data returned in
       * the row parameter and the index of the cell
       */
      const backgroundColor = () => {
        if (row.company && row.company === 'Google') {
          if (colIndex === 0) {
            return '#4285F4'
          } else if (colIndex === 1) {
            return '#DB4437'
          } else {
            return '#F4B400'
          }
        }

        return ''
      }

      /**
       * Returns an object of attributes to be applied to cells
       */
      return {
        class: {
          'truncate': headerKey === 'description' || headerKey === 'name',
        },
        'datatest-id': `row-${rowIndex + 1}-col-${headerKey}`,
        style: {
          'maxWidth': headerKey === 'description' ? '50ch' : headerKey === 'name' ? '22ch' : '25ch',
          'backgroundColor': backgroundColor(),
        },
      }
    }
  }
}
</script>

# Events

Bind any DOM events to various parts of the table. We support events on both table rows and cells in addition to click elements inside a row (ie. buttons or hyperlinks) without triggering the a row or cell event. You can also add logic to check for metakey to support cmd/ctrl when clicking. Examples highlighted below.

# Rows

@row:<event> - returns the Event, the row item, and the type: row

<KTable @row:click="rowHandler" @row:dblclick="rowHandler">





 

 






 














 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
<KTable
  :fetcher="fetcher"
  :headers="headers"
  @row:click="handleRowClick">
  <template v-slot:company="{rowValue}">
    <a v-if="rowValue" @click="linkHander">{{rowValue.label}}</a>
    <span v-else>{{rowValue}}</span>
  </template>
  <template v-slot:actions>
    <div class="float-right">
      <KButton
        appearance="secondary"
        @click="buttonHandler">
        Visit Website
      </KButton>
    </div>
  </template>
</KTable>
<script>
export default {
  data() {
    return {
      row: null,
      eventType: ''
    }
  },
  methods: {
    handleRowClick(e, row) {
      const metaKeyPressed = e.metaKey || e.ctrlKey

      if (metaKeyPressed) {
        return window.open(row.company.href)
      } else {
        window.location = row.company.href
      }
    },
    linkHander (e) {
      alert('a link was clicked')
    },
    buttonHandler (e) {
      alert('a button was pressed')
    }
  }
}
</script>

# Cells

@cell:<event> - returns the Event, the cell value, and the type: cell

<KTable @cell:mouseout="cellHandler" @cell:mousedown="cellHandler">
Waiting

# Example

<template>
  <div>
    <div v-if="eventType">
      {{eventType}} on: {{row}}
    </div>
    <div v-else>Waiting</div>
    <KTable
      :fetcher="fetcher"
      :headers="headers"
      is-clickable
      @row:click="actionRow"
      @cell:mouseover="actionRow"
    />
  </div>
</template>

<template>
  <KCard>
    <template v-slot:body>
      <div v-if="eventType">
        {{eventType}} on: {{row}}
      </div>
      <div v-else>Waiting</div>
      <KTable
        :fetcher="fetcher"
        :headers="headers"
        is-clickable
        has-hover
        @row:click="actionRow"
        @cell:mouseover="actionRow"
      />
    </template>
  </KCard>
</template>

<script>
export default {
  data() {
    return {
      row: null,
      eventType: ''
    }
  },
  methods: {
    actionRow (e, row, type) {
      this.eventType = e.type
      this.row = row
    }
  }
}
</script>

# Slots

Both column cells & header cells are slottable in KTable. Use slots to gain access to the row data.

  • column-{column-key} - Will slot the header cell
  • {column-key} - Will slot the column cell of a given row

# Column Header

<template>
  <KTable
    :fetcher="fetcher"
    :headers="headers"
  >
    <!-- Slot column header "name" -->
    <template v-slot:column-name="{ column }">
      {{ column.label.toUpperCase() }}
    </template>
  </KTable>
</template>

<script>
export default {
  data() {
    return {
      headers: [
        { key: 'name', label: 'Name', sortable: false },
        { key: 'id', label: 'ID', sortable: false },
        { key: 'enabled', label: 'Enabled', sortable: false }
      ]
    }
  }
}
</script>

# Column Cell

<template>
  <KTable
    :fetcher="fetcher"
    :headers="headers"
  >
    <!-- Slot each "enabled" cell in each row & add icon if matching value -->
    <template v-slot:enabled="{rowValue}">
      <span v-if="rowValue" style="color: green">&#10003;</span>
      <span v-else style="color: red">&#10007;</span>
    </template>
    <!-- Slot each "actions" cell in each row & link -->
    <template v-slot:actions><a href="">Edit</a></template>
  </KTable>
</template>
<script>
export default {
  data() {
    return {
      headers: [
        { key: 'name', label: 'Name', sortable: false },
        { key: 'id', label: 'ID', sortable: false },
        { key: 'enabled', label: 'Enabled', sortable: false }
      ]
    }
  }
}
</script>

# State Slots

KTable has built-in state management for loading, empty, and error states. You can either use the props described in the section below or completely slot in your own content.

  • empty-state - Slot content to be displayed when empty
  • error-state - Slot content to be displayed when in an error state
<template>
  <KTable
    :fetcher="() => { return { data: [] } }"
    :headers="headers"
  >
    <template v-slot:empty-state>
      <KIcon icon="warning" />
      No Content!!!
    </template>
    <template v-slot:error-state>
      <KIcon icon="error" />
      Something went wrong
    </template>
  </KTable>
</template>

# States

# Empty

Set the following properties to handle empty state:

  • emptyStateTitle - Title text for empty state
  • emptyStateMessage - Message for empty state
  • emptyStateIcon - Icon for empty state
  • emptyStateIconColor - Color for empty state icon
  • emptyStateIconSize - Size for empty state icon
  • emptyStateActionRoute - Route for empty state action
  • emptyStateActionMessage - Button text for empty state action
  • emptyStateActionButtonIcon - Icon for the empty state action button

If using a CTA button, a ktable-empty-state-cta-clicked event is fired when clicked.

# Default Empty State Messaging

<template>
  <KCard>
    <template v-slot:body>
      <KTable
        :fetcher="fetcher"
        :headers="headers" />
    </template>
  </KCard>
</template>

# Empty State Full Example

<!-- Using a route string -->
<template>
  <KCard>
    <template v-slot:body>
      <KTable
        :fetcher="fetcher"
        :headers="headers"
        emptyStateTitle="No Workspaces exist"
        emptyStateMessage="Adding a new Workspace will populate this table."
        emptyStateActionMessage="Create a Workspace"
        emptyStateActionButtonIcon="plus"
        emptyStateActionRoute="create-workspace"
        emptyStateIcon="workspaces"
        emptyStateIconColor="#5996ff"
        emptyStateIconSize="35" />
    </template>
  </KCard>
</template>

<!-- Using a route object -->
<template>
  <KCard>
    <template v-slot:body>
      <KTable
        :fetcher="fetcher"
        :headers="headers"
        emptyStateTitle="No Workspaces exist"
        emptyStateMessage="Adding a new Workspace will populate this table."
        emptyStateActionMessage="Create a Workspace"
        emptyStateActionButtonIcon="plus"
        emptyStateActionRoute="{
          name: 'create-workspace',
          params: {
            organizationId: 'd27e40e0-c9ac-43e2-8be8-54862fab45ea'
          }
        }"
        emptyStateIcon="workspaces"
        emptyStateIconColor="#5996ff"
        emptyStateIconSize="35" />
    </template>
  </KCard>
</template>

# Error

Set the following properties to handle error state:

  • hasError - Boolean to toggle error state
  • errorStateTitle - Title text for error state
  • errorStateMessage - Message for error state
  • errorStateIcon - Icon for error state
  • errorStateIconColor - Color for error state icon
  • errorStateIconSize - Size for error state icon
  • errorStateActionRoute - Route for error state action
  • errorStateActionMessage - Button text for error state action

If using a CTA button, a ktable-error-cta-clicked event is fired when clicked.

# Default Error State Messaging

Warning
An error occurred
Data cannot be displayed due to an error.
<template>
  <KCard>
    <template v-slot:body>
      <KTable
        :fetcher="fetcher"
        :headers="headers"
        :hasError="true" />
    </template>
  </KCard>
</template>

# Error State Full Example

Danger
Something went wrong
We are not able to load the data for this table.
Report an Issue 
<!-- Using a route string -->
<template>
  <KCard>
    <template v-slot:body>
      <KTable
        :fetcher="fetcher"
        :headers="headers"
        :hasError="true"
        errorStateTitle="Something went wrong"
        errorStateMessage="We are not able to load the data for this table."
        errorStateActionMessage="Report an Issue"
        errorStateActionRoute="report-issue"
        errorStateIcon="dangerCircle"
        errorStateIconColor="#e6173a"
        errorStateIconSize="35" />
    </template>
  </KCard>
</template>

<!-- Using a route object -->
<template>
  <KCard>
    <template v-slot:body>
      <KTable
        :fetcher="fetcher"
        :headers="headers"
        :hasError="true"
        errorStateTitle="Something went wrong"
        errorStateMessage="We are not able to load the data for this table."
        errorStateActionMessage="Report an Issue"
        errorStateActionRoute="{
          name: 'report-issue',
          params: {
            organizationId: 'd27e40e0-c9ac-43e2-8be8-54862fab45ea'
          }
        }"
        errorStateIcon="dangerCircle"
        errorStateIconColor="#e6173a"
        errorStateIconSize="35" />
    </template>
  </KCard>
</template>

# Loading

Set the isLoading prop to true to enable the loading state.

<template>
<KCard>
  <template v-slot:body>
    <KTable
      :fetcher="fetcher"
      :headers="headers"
      :isLoading="true" />
  </template>
</KCard>
</template>

# Server-side functions

Pass a fetcher function to enable server-side search, sort and pagination. The fetcher function should structure the ajax request URL in such a way that enables server side sort, search and pagination per the requirements of the API being used.

Note

The loading state is handled automatically. When the fetcher is called the internal loading state is triggered and will be resolved when the fetcher returns. You can override this behavior using the isLoading prop.

Example URL

https://kongponents.dev/api/components?_page=1&_limit=10&_sort=name&_order=desc

<!-- Example Component Usage -->

<KCard>
  <template v-slot:body>
    <KInput placeholder="Search..." v-model="search" type="search" />
    <KTable
      :fetcher="fetcher"
      :initial-fetcher-params="{
        pageSize: 15,
        page: 1,
        query: '',
        sortColumnKey: '',
        sortColumnOrder: ''
      }"
      :headers="[
        { label: 'Title', key: 'title', sortable: true },
        { label: 'Description', key: 'description', sortable: true },
        { label: 'Enabled', key: 'enabled', sortable: false }
      ]"
      :search-input="search"
    />
  </template>
</KCard>

// Example Fetcher Function

fetcher(payload) {
  const params = {
    _limit: payload.pageSize,
    _page: payload.page
  }

  if (query) {
    params.q = payload.query
    params._page = 1
  }

  if (sortKey) {
    params._sort = payload.sortColumnKey
    params._order = payload.sortColumnOrder
  }

  return axios.get('/user_list', {
    baseURL: 'https://kongponents.dev/api',
    params
  }).then(res => {
    return {
      total: res.total,
      data: res.data
    }
  })
}

# Theming

Variable Purpose
--KTableBorder Sets cell border color
--KTableColor Font color
--KTableHover Hover variant background color
--KTableHeaderSize Font size of header th


An Example of changing the hover background might look like.

<template>
  <KTable
    :fetcher="fetcher"
    :headers="headers"
    hasHover />
</template>

<style>
:root {
  --KTableHover: lavender;
}
</style>

← Table (legacy) →