arthur/ui
1
0
Fork 0
mirror of https://github.com/ArthurDanjou/ui.git synced 2026-01-14 20:19:34 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
90a775bab93354095cf50086f0124c627486b859
ui/docs/content/3.components/table.md
Benjamin Canac 90a775bab9 docs(table): update
2024-10-23 17:49:17 +02:00

11 KiB
Raw Blame History

description, links
description links
A responsive table element to display data in rows and columns.
label avatar to
TanStack Table
src
https://github.com/tanstack.png
https://tanstack.com/table/latest
label icon to
GitHub i-simple-icons-github https://github.com/nuxt/ui/tree/v3/src/runtime/components/Table.vue

Usage

The Table component is built on top of TanStack Table and is powered by the useVueTable composable to provide a flexible and fully type-safe API.

::component-example

source: false name: 'table-example' class: '!p-0'

::

::callout{icon="i-simple-icons-github" to="https://github.com/nuxt/ui/tree/v3/docs/app/components/content/examples/table/TableExample.vue"} This example demonstrates the most common use case of the Table component. Check out the source code on GitHub. ::

::note Some features of TanStack Table are not supported yet, we'll add more over time. ::

Data

Use the data prop as an array of objects, the columns will be generated based on the keys of the objects.

::component-code

collapse: true class: '!p-0' ignore:

::

Columns

Use the columns prop as an array of ColumnDef objects with properties like:

  • accessorKey: [The key of the row object to use when extracting the value for the column.]{class="text-[var(--ui-text-muted)]"}
  • header: [The header to display for the column. If a string is passed, it can be used as a default for the column ID. If a function is passed, it will be passed a props object for the header and should return the rendered header value (the exact type depends on the adapter being used).]{class="text-[var(--ui-text-muted)]"}
  • cell: [The cell to display each row for the column. If a function is passed, it will be passed a props object for the cell and should return the rendered cell value (the exact type depends on the adapter being used).]{class="text-[var(--ui-text-muted)]"}

In order to render components or other HTML elements, you will need to use the Vue h function inside the header and cell props. This is different from other components that use slots but allows for more flexibility.

::component-example

prettier: true collapse: true class: '!p-0' name: 'table-columns-example' highlights:

  • 53
  • 105

::

::tip When rendering components with the h function, you can utilize the resolveComponent function to dynamically resolve and reference components. ::

Loading

Use the loading prop to display a loading state, the loading-color prop to change its color and the loading-animation prop to change its animation.

::component-code

collapse: true class: '!p-0' ignore:

  • data
  • class external:
  • data props: loading: true loadingColor: primary loadingAnimation: carousel data:

::

Sticky

Use the sticky prop to make the header sticky.

::component-code

collapse: true class: '!p-0' ignore:

::

Examples

With row actions

You can add a new column that renders a DropdownMenu component inside the cell to render row actions.

::component-example

prettier: true collapse: true name: 'table-row-actions-example' highlights:

  • 110
  • 134 class: '!p-0'

::

With expandable rows

You can add a new column that renders a Button component inside the cell to toggle the expandable state of a row using the TanStack Table Expanding APIs.

::caution You need to define the #expanded slot to render the expanded content which will receive the row as a parameter. ::

::component-example

prettier: true collapse: true name: 'table-row-expandable-example' highlights:

  • 55
  • 71 class: '!p-0'

::

::tip You can use the expanded prop to control the expandable state of the rows (can be binded with v-model). ::

::note You could also add this action to the DropdownMenu component inside the actions column. ::

With row selection

You can add a new column that renders a Checkbox component inside the header and cell to select rows using the TanStack Table Row Selection APIs.

::component-example

prettier: true collapse: true name: 'table-row-selection-example' highlights:

  • 55
  • 70 class: '!p-0'

::

::tip You can use the row-selection prop to control the selection state of the rows (can be binded with v-model). ::

With column sorting

You can update a column header to render a Button component inside the header to toggle the sorting state using the TanStack Table Sorting APIs.

::component-example

prettier: true collapse: true name: 'table-column-sorting-example' highlights:

  • 90
  • 105 class: '!p-0'

::

::tip You can use the sorting prop to control the sorting state of the columns (can be binded with v-model). ::

You can also create a reusable component to make any column header sortable.

::component-example

prettier: true collapse: true name: 'table-column-sorting-reusable-example' highlights:

  • 110
  • 161 class: '!p-0'

::

::note In this example, we use a function to define the column header but you can also create an actual component. ::

With column pinning

You can update a column header to render a Button component inside the header to toggle the pinning state using the TanStack Table Pinning APIs.

::note A pinned column will become sticky on the left or right side of the table. ::

::component-example

prettier: true collapse: true name: 'table-column-pinning-example' highlights:

  • 100
  • 113 class: '!p-0 overflow-clip'

::

::tip You can use the column-pinning prop to control the pinning state of the columns (can be binded with v-model). ::

With column visibility

You can add use DropdownMenu component to toggle the visibility of the columns using the TanStack Table Column Visibility APIs.

::component-example

prettier: true collapse: true name: 'table-column-visibility-example' highlights:

  • 135
  • 142 class: '!p-0'

::

::tip You can use the column-visibility prop to control the visibility state of the columns (can be binded with v-model). ::

With column filters

You can use an Input component to filter per column the rows using the TanStack Table Column Filtering APIs.

::component-example

prettier: true collapse: true name: 'table-column-filters-example' highlights:

  • 135
  • 142 class: '!p-0'

::

::tip You can use the column-filters prop to control the filters state of the columns (can be binded with v-model). ::

With global filter

You can use an Input component to filter the rows using the TanStack Table Global Filtering APIs.

::component-example

prettier: true collapse: true name: 'table-global-filter-example' class: '!p-0'

::

::tip You can use the global-filter prop to control the global filter state (can be binded with v-model). ::

With fetched data

You can fetch data from an API and use them in the Table.

::component-example

prettier: true collapse: true name: 'table-fetch-example' class: '!p-0'

::

API

Props

:component-props

Slots

:component-slots

Expose

You can access the typed component instance using useTemplateRef.

<script setup lang="ts">
const table = useTemplateRef('table')
</script>

<template>
  <UTable ref="table" />
</template>

This will give you access to the following:

Name Type
tableApi{lang="ts-type"} Ref<Table | null>{lang="ts-type"}

Theme

:component-theme

Reference in New Issue View Git Blame Copy Permalink