Kongponents

Catalog ​

KCatalog - a grid view of KCards.

html
<KCatalog :fetcher="fetcher" />

Props ​

title ​

The catalog title.

Cards Catalog
html
<KCatalog title="Cards Catalog" :fetcher="fetcher" />

titleTag ​

HTML element you want title to be rendered as. Defaults to div.

Accepted values are:

  • div
  • p
  • span
  • a
  • legend
  • h1
  • h2
  • h3
  • h4
  • h5
  • h6

cardSize ​

Size of the cards. Supports values small, medium (default), and large.

Small Cards
Medium Cards
Large Cards
html
<KCatalog card-size="small" title="Small Cards" :fetcher="fetcher" hide-pagination-when-optional />
<KCatalog title="Medium Cards" :fetcher="fetcher" />
<KCatalog card-size="large" title="Large Cards" :fetcher="fetcher" hide-pagination-when-optional />

truncateDescription ​

By default long card body text is truncated at 3 lines. Set this prop to false to turn truncation off.

Truncating card body
Truncation disabled
html
<KCatalog title="Truncating card body" :fetcher="fetcherLong" hide-pagination-when-optional />
<KCatalog :truncate-description="false" title="Truncation disabled" :fetcher="fetcherLong" hide-pagination-when-optional />

error ​

Boolean to control whether KCatalog should display error state. Defaults to false.

loading ​

Boolean to control whether KCatalog should display loading state. Defaults to false.

fetcher ​

Use a custom fetcher function to fetch card catalog items and leverage server-side pagination. Fetcher functions takes a single optional param (see initialFetcherParams prop) as an object with following properties:

ts
// fetcher function param
{
  page: number, // the currently visible page (default value is 1)
  pageSize: number, // the number of items to display per page (default value is 15)
  query: string // search query if search is supported
}

The return value of the fetcher function should be an object with the following properties:

ts
// fetcher function return
{ 
  total: number, // the total count of catalog items (if using pagination)
  data: CatalogItem[] // an array of catalog items
}
ts
interface CatalogItem {
  id?: string
  title: string
  description: string
  key?: string // optional parameter to be used as key in v-for, has to be unique for each item
}

Example fetcher function:

ts
const fetcher = (payload: { page: number, pageSize: number, query: string }) => {
  const params = {
    _limit: payload.pageSize,
    _page: payload.page
  }

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

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 loading prop.

initialFetcherParams ​

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

ts
{ 
  pageSize: 15,
  page: 1
}

cacheIdentifier ​

The fetcher functionality makes use of SWRV to handle caching of response data. In order to take advantage of this caching, SWRV needs a way to identify which cache entry is associated with the catalog.

The identifier should be a string and will default to '' if not provided. In that scenario, we will generate a random ID for the identifier every time the catalog is mounted.

DANGER

This identifier must be unique across all KCatalog instances across the entire Vue app, otherwise there is a risk that SWRV will return the cached data of the wrong catalog.

fetcherCacheKey ​

Whenever the cache key is changed the fetcher will automatically be called and attempt to fetch new catalog data.

vue
<template>
  <KCatalog
    cache-identifier="fetcher-cache-key-example-catalog"
    :fetcher="fetcher"
    :fetcher-cache-key="cacheKey"
  />
</template>

<script setup lang="ts">
const cacheKey = ref<number>(1)

const itemDeleted = () => {
  // take an action on the DOM
  cacheKey.value++ // triggers refetch
}
</script>

searchInput ​

Pass in a string of search input for server-side table filtering.

Pagination ​

KCatalog uses KPagination component under the hood and exposes a few props as a way to modify how pagination looks and behaves in card catalogs. See KPagination docs for more details and examples:

  • paginationTotalItems
  • paginationNeighbors
  • paginationPageSizes
  • paginationOffset
  • disablePaginationPageJump

disablePagination ​

Set this to true to hide pagination when using a fetcher.

hidePaginationWhenOptional ​

Set this to true to hide pagination when the table record count is less than or equal to the pageSize.

States ​

Empty ​

html
<KCatalog :fetcher="emptyFetcher" />

Set the following props to handle empty state:

  • emptyStateTitle - Title text for empty state
  • emptyStateMessage - Message for empty state
  • emptyStateIconVariant - Icon variant for empty state (see KEmptyState component props)
  • emptyStateActionMessage - Button text for empty state action
  • emptyStateActionRoute - Route for empty state action

TIP

Should you want to display an icon inside of action button, you can use empty-state-action-icon slot.

When empty state action button is clicked, KCatalog emits the empty-state-action-click event.

html
<KCatalog 
  :fetcher="emptyFetcher"
  empty-state-title="No Workspaces exist"
  empty-state-message="Adding a new Workspace will populate this catalog."
  empty-state-icon-variant="kong"
  empty-state-action-message="Create a Workspace"
  empty-state-action-route="#empty-state-full-example"
>
  <template #empty-state-action-icon>
    <AddIcon />
  </template>
</KCatalog>

Error ​

Set the error prop to true to enable the error state.

An error occurred

Data cannot be displayed due to an error.

html
<KCatalog error :fetcher="fetcher" />

Set the following properties to customize error state:

  • errorStateTitle - Title text for error state
  • errorStateMessage - Message for error state
  • errorStateActionMessage - Button text for error state action
  • errorStateActionRoute - Route for error state action

A error-action-click event is fired when error state action button is clicked.

Something went wrong

Error loading data.

Report an Issue
html
<KCatalog
  :fetcher="fetcher"
  :error="true"
  error-state-title="Something went wrong"
  error-state-message="Error loading data."
  error-state-action-message="Report an Issue"
  error-state-action-route="#error-state-full-example"
/>

Loading ​

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

html
<KCatalog loading :fetcher="fetcher" />

Slots ​

Both the title & description of the card items as well as the entire catalog body are slottable.

body ​

The body of the card catalog, if you do not want to use KCatalogItem components for the children.

card-title ​

Will slot the card title for each entry. The slot exposes card item through the item slot prop.

html
<KCatalog :fetcher="fetcher">
  <template #card-title="{ item }">
    {{ item.key % 2 ? 'Odd' : 'Even' }} item
  </template>
</KCatalog>

card-actions ​

Slot the card actions for each entry. The slot exposes card item through the item slot prop.

html
<KCatalog :fetcher="fetcher">
  <template #card-actions="{ item }">
    <KDropdown :items="items">
      <KButton size="small" :title="`${item.title} actions`" appearance="secondary">
        <template #icon>
          <MoreIcon />
        </template>
      </KButton>
    </KDropdown>
  </template>
</KCatalog>

card-body ​

Will slot the card body for each entry. The slot exposes card item through the item slot prop.

toolbar ​

The toolbar slot allows you to slot catalog controls rendered at the top of the .k-catalog element such as a search input or other UI elements. It provides the SWRV state and hasData in the slot param.

ts
{
  state: {
    hasData: boolean
    state: string
  }
}
html
<KCatalog :fetcher="fetcher">
  <template #toolbar="{ state }">
    <KInput
      v-if="state.hasData"
      placeholder="Search"
    />
    <KSelect
      appearance="select"
      :items="[
        { label: 'First option', value: '1', selected: true },
        { label: 'Another option', value: '2'}
      ]"
    />
  </template>
</KCatalog>

empty-state ​

Slot content to be displayed when empty.

empty-state-action-icon ​

Slot for icon to be displayed in front of action button text in empty state. See empty state section for example of usage of this slot.

error-state ​

Slot content to be displayed when in error state.

Events ​

card-click ​

Emitted when a KCatalogItem is clicked, the payload is the clicked item's object.

empty-state-action-click ​

Emitted when empty state action button is clocked.

error-action-click ​

Emitted when error state action button is clicked.

update:catalog-preferences ​

Fired when the user changes the catalog's pageSize.

Returns a payload that adheres to the CatalogPreferences interface:

ts
interface CatalogPreferences {
  /** The number of items to display per page */
  pageSize?: number
}

state ​

Fired when the catalog state changes.

Returns the state and hasData (boolean) of the catalog, state can be one of:

  • loading - when the catalog is fetching new catalog data
  • error - when the catalog fetch failed
  • success - when the catalog fetch completed successfully

KCatalogItem ​

KCatalog generates a KCatalogItem for each item in the items property. At the most basic level, KCatalogItem is a wrapper around KCard to display correctly inside KCatalog. You can use the body slot of the KCatalog to manually create your own catalog items.

Props ​

item ​

Object instance of CatalogItem from which card content is built.

truncate ​

A boolean (default to true), whether or not to truncate the description text.

html
<KCatalogItem :item="item" :truncate="false" class="catalog-item" />

Slots ​

card-title ​

The title content for the card.

card-body ​

The body content for the card.

The footer content for the card.

Card Title
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi nec justo libero. Nullam accumsan quis ipsum vitae tempus. Integer non pharetra orci. Suspendisse potenti.
Card footer
html
<KCatalogItem>
  <template #card-title>
    Card Title
  </template>
  <template #card-body>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi nec justo libero. Nullam accumsan quis ipsum vitae tempus. Integer non pharetra orci. Suspendisse potenti.
  </template>
  <template #card-footer>
      <KBadge appearance="neutral">Card footer</KBadge>
  </template>
</KCatalogItem>

Events ​

click ​

Fired when item is clicked. Event payload is item object.

Released under the Apache-2.0 License.

Copyright © 2019-present Kong, Inc.