Table

Uso

O componente Table é construído sobre o TanStack Table e usa o composable useVueTable para oferecer uma API flexível e totalmente type-safe.

Ele renderiza os seus dados em linhas e colunas e suporta ordenação, filtragem, paginação, seleção de linhas, expansão, agrupamento, fixação e virtualização, então você pode construir desde uma tabela de dados simples até um data grid completo.

Dados

Use a prop data como um array de objetos; as colunas serão geradas com base nas chaves dos objetos.

<script setup lang="ts">
const data = ref([
  {
    id: '4600',
    date: '2024-03-11T15:30:00',
    status: 'paid',
    email: '[email protected]',
    amount: 594
  },
  {
    id: '4599',
    date: '2024-03-11T10:10:00',
    status: 'failed',
    email: '[email protected]',
    amount: 276
  },
  {
    id: '4598',
    date: '2024-03-11T08:50:00',
    status: 'refunded',
    email: '[email protected]',
    amount: 315
  },
  {
    id: '4597',
    date: '2024-03-10T19:45:00',
    status: 'paid',
    email: '[email protected]',
    amount: 529
  },
  {
    id: '4596',
    date: '2024-03-10T15:55:00',
    status: 'paid',
    email: '[email protected]',
    amount: 639
  }
])
</script>

<template>
  <NTable :data="data" class="flex-1" />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const data = ref([
  {
    id: '4600',
    date: '2024-03-11T15:30:00',
    status: 'paid',
    email: '[email protected]',
    amount: 594
  },
  {
    id: '4599',
    date: '2024-03-11T10:10:00',
    status: 'failed',
    email: '[email protected]',
    amount: 276
  },
  {
    id: '4598',
    date: '2024-03-11T08:50:00',
    status: 'refunded',
    email: '[email protected]',
    amount: 315
  },
  {
    id: '4597',
    date: '2024-03-10T19:45:00',
    status: 'paid',
    email: '[email protected]',
    amount: 529
  },
  {
    id: '4596',
    date: '2024-03-10T15:55:00',
    status: 'paid',
    email: '[email protected]',
    amount: 639
  }
])
</script>

<template>
  <NTable :data="data" class="flex-1" />
</template>

Colunas

Use a prop columns como um array de objetos ColumnDef com propriedades como:

• accessorKey: The key of the row object to use when extracting the value for the column.
• 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).
• footer: The footer to display for the column. Works exactly like header, but is displayed under the table.
• 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).
• meta: Extra properties for the column.
  • class:
    • td: The classes to apply to the td element.
    • th: The classes to apply to the th element.
  • style:
    • td: The style to apply to the td element.
    • th: The style to apply to the th element.
  • colspan:
    • td: The colspan attribute to apply to the td element.
  • rowspan:
    • td: The rowspan attribute to apply to the td element.

Para renderizar componentes ou outros elementos HTML, você precisará usar a função h do Vue dentro das props header e cell. Isso é diferente de outros componentes que usam slots, mas permite mais flexibilidade.

Meta

Use a prop meta como um objeto (TableMeta) para passar propriedades como:

• class:
  • tr: The classes to apply to the tr element.
• style:
  • tr: The style to apply to the tr element.

Carregando

Use a prop loading para exibir um estado de carregamento, a prop loading-color para alterar a cor dele e a prop loading-animation para alterar a animação dele.

<script setup lang="ts">
const data = ref([
  {
    id: '4600',
    date: '2024-03-11T15:30:00',
    status: 'paid',
    email: '[email protected]',
    amount: 594
  },
  {
    id: '4599',
    date: '2024-03-11T10:10:00',
    status: 'failed',
    email: '[email protected]',
    amount: 276
  },
  {
    id: '4598',
    date: '2024-03-11T08:50:00',
    status: 'refunded',
    email: '[email protected]',
    amount: 315
  },
  {
    id: '4597',
    date: '2024-03-10T19:45:00',
    status: 'paid',
    email: '[email protected]',
    amount: 529
  },
  {
    id: '4596',
    date: '2024-03-10T15:55:00',
    status: 'paid',
    email: '[email protected]',
    amount: 639
  }
])
</script>

<template>
  <NTable
    loading
    loading-color="primary"
    loading-animation="carousel"
    :data="data"
    class="flex-1"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const data = ref([
  {
    id: '4600',
    date: '2024-03-11T15:30:00',
    status: 'paid',
    email: '[email protected]',
    amount: 594
  },
  {
    id: '4599',
    date: '2024-03-11T10:10:00',
    status: 'failed',
    email: '[email protected]',
    amount: 276
  },
  {
    id: '4598',
    date: '2024-03-11T08:50:00',
    status: 'refunded',
    email: '[email protected]',
    amount: 315
  },
  {
    id: '4597',
    date: '2024-03-10T19:45:00',
    status: 'paid',
    email: '[email protected]',
    amount: 529
  },
  {
    id: '4596',
    date: '2024-03-10T15:55:00',
    status: 'paid',
    email: '[email protected]',
    amount: 639
  }
])
</script>

<template>
  <NTable
    loading
    loading-color="primary"
    loading-animation="carousel"
    :data="data"
    class="flex-1"
  />
</template>

Fixo

Use a prop sticky para tornar o cabeçalho ou o rodapé fixos.

<script setup lang="ts">
const data = ref([
  {
    id: '4600',
    date: '2024-03-11T15:30:00',
    status: 'paid',
    email: '[email protected]',
    amount: 594
  },
  {
    id: '4599',
    date: '2024-03-11T10:10:00',
    status: 'failed',
    email: '[email protected]',
    amount: 276
  },
  {
    id: '4598',
    date: '2024-03-11T08:50:00',
    status: 'refunded',
    email: '[email protected]',
    amount: 315
  },
  {
    id: '4597',
    date: '2024-03-10T19:45:00',
    status: 'paid',
    email: '[email protected]',
    amount: 529
  },
  {
    id: '4596',
    date: '2024-03-10T15:55:00',
    status: 'paid',
    email: '[email protected]',
    amount: 639
  },
  {
    id: '4595',
    date: '2024-03-10T15:55:00',
    status: 'paid',
    email: '[email protected]',
    amount: 639
  },
  {
    id: '4594',
    date: '2024-03-10T15:55:00',
    status: 'paid',
    email: '[email protected]',
    amount: 639
  }
])
</script>

<template>
  <NTable sticky :data="data" class="flex-1 max-h-[312px]" />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const data = ref([
  {
    id: '4600',
    date: '2024-03-11T15:30:00',
    status: 'paid',
    email: '[email protected]',
    amount: 594
  },
  {
    id: '4599',
    date: '2024-03-11T10:10:00',
    status: 'failed',
    email: '[email protected]',
    amount: 276
  },
  {
    id: '4598',
    date: '2024-03-11T08:50:00',
    status: 'refunded',
    email: '[email protected]',
    amount: 315
  },
  {
    id: '4597',
    date: '2024-03-10T19:45:00',
    status: 'paid',
    email: '[email protected]',
    amount: 529
  },
  {
    id: '4596',
    date: '2024-03-10T15:55:00',
    status: 'paid',
    email: '[email protected]',
    amount: 639
  },
  {
    id: '4595',
    date: '2024-03-10T15:55:00',
    status: 'paid',
    email: '[email protected]',
    amount: 639
  },
  {
    id: '4594',
    date: '2024-03-10T15:55:00',
    status: 'paid',
    email: '[email protected]',
    amount: 639
  }
])
</script>

<template>
  <NTable sticky :data="data" class="flex-1 max-h-[312px]" />
</template>

Exemplos

Com ações de linha

Você pode adicionar uma nova coluna que renderiza um componente DropdownMenu dentro da cell para renderizar ações de linha.

Com linhas expansíveis

Você pode adicionar uma nova coluna que renderiza um componente Button dentro da cell para alternar o estado expansível de uma linha usando as APIs de Expanding do TanStack Table.

{
  "id": "4599",
  "date": "2024-03-11T10:10:00",
  "status": "failed",
  "email": "[email protected]",
  "amount": 276
}

Com linhas agrupadas

Você pode agrupar as linhas com base no valor de uma coluna e exibir/ocultar as sublinhas por meio de algum botão adicionado à célula usando as APIs de Grouping do TanStack Table.

Partes importantes:

• Add grouping prop with an array of column ids you want to group by.
• Add grouping-options prop. It must include getGroupedRowModel, you can import it from @tanstack/vue-table or implement your own.
• Expand rows via row.toggleExpanded() method on any cell of the row. Keep in mind, it also toggles #expanded slot.
• Use aggregateFn on column definition to define how to aggregate the rows.
• agregatedCell renderer on column definition only works if there is no cell renderer.

Com fixação de linhas 4.6+

Você pode adicionar uma coluna que renderiza um componente Button dentro da cell para alternar o estado de fixação de uma linha usando as APIs de Row Pinning do TanStack Table. Linhas fixadas permanecem no topo ou na base da tabela, independentemente da ordenação ou filtragem.

Com seleção de linhas

Você pode adicionar uma nova coluna que renderiza um componente Checkbox dentro do header e da cell para selecionar linhas usando as APIs de Row Selection do TanStack Table.

Com evento de seleção da linha

Você pode adicionar um listener @select para tornar as linhas clicáveis com ou sem uma coluna de checkbox.

Com evento de menu de contexto da linha

Você pode adicionar um listener @contextmenu para tornar as linhas clicáveis com o botão direito e envolver a Table em um componente ContextMenu para exibir ações de linha, por exemplo.

Com evento de hover da linha

Você pode adicionar um listener @hover para tornar as linhas sensíveis ao hover e usar um componente Popover ou Tooltip para exibir os detalhes da linha, por exemplo.

Com rodapé de coluna

Você pode adicionar uma propriedade footer à definição da coluna para renderizar um rodapé para a coluna.

Com span de coluna

Você pode usar as propriedades colspan e rowspan no meta da coluna para mesclar células. Essas propriedades aceitam um valor estático ou uma função que recebe a célula e retorna o valor do span.

Com ordenação de colunas

Você pode atualizar o header de uma coluna para renderizar um componente Button dentro do header para alternar o estado de ordenação usando as APIs de Sorting do TanStack Table.

Você também pode criar um componente reutilizável para tornar o cabeçalho de qualquer coluna ordenável.

Com fixação de colunas

Você pode atualizar o header de uma coluna para renderizar um componente Button dentro do header para alternar o estado de fixação usando as APIs de Pinning do TanStack Table.

Com visibilidade de colunas

Você pode usar um componente DropdownMenu para alternar a visibilidade das colunas usando as APIs de Column Visibility do TanStack Table.

Com filtros de coluna

Você pode usar um componente Input para filtrar as linhas por coluna usando as APIs de Column Filtering do TanStack Table.

Com filtro global

Você pode usar um componente Input para filtrar as linhas usando as APIs de Global Filtering do TanStack Table.

Com paginação

Você pode usar um componente Pagination para controlar o estado de paginação usando as APIs de Pagination.

Há diferentes abordagens de paginação, como explicado no Guia de Paginação. Neste exemplo, usamos paginação no lado do cliente, então precisamos passar manualmente a função getPaginationRowModel().

Com dados buscados

Você pode buscar dados de uma API e usá-los na Table.

Com rolagem infinita

Se você usa paginação no lado do servidor, pode usar o composable useInfiniteScroll para carregar mais dados conforme o usuário rola.

Com arrastar e soltar

Você pode usar o composable useSortable de @vueuse/integrations para habilitar a funcionalidade de arrastar e soltar na Table. Essa integração envolve o Sortable.js para oferecer uma experiência de arrastar e soltar fluida.

Com virtualização 4.1+

Use a prop virtualize para habilitar a virtualização em grandes conjuntos de dados, como um booleano ou um objeto com opções como { estimateSize: 65, overscan: 12 }. Você também pode passar outras opções do TanStack Virtual para personalizar o comportamento da virtualização. A prop sticky funciona em combinação com virtualize para manter o cabeçalho ou o rodapé visíveis ao rolar por grandes conjuntos de dados.

Com elemento de rolagem externo Soon

Passe uma função getScrollElement na prop virtualize para virtualizar em relação a um container de rolagem ancestral em vez do próprio root da tabela. Defina scrollMargin como o deslocamento da tabela em relação ao início do elemento de rolagem (ex.: a altura do conteúdo acima dela), para que um cabeçalho e o corpo da tabela compartilhem uma única barra de rolagem.

Com dados de árvore

Você pode usar a prop get-sub-rows para exibir dados hierárquicos (em árvore) na tabela. Por exemplo, se os seus objetos de dados têm um array children, defina :get-sub-rows="row => row.children" para habilitar linhas expansíveis.

Com slots

Você pode usar slots para personalizar o cabeçalho e as células de dados da tabela.

Use o slot #<column>-header para personalizar o cabeçalho de uma coluna. Você terá acesso às propriedades column, header e table no escopo do slot.

Use o slot #<column>-cell para personalizar a célula de uma coluna. Você terá acesso às propriedades cell, column, getValue, renderValue, row e table no escopo do slot.

ID	Name	E-mail	Role
1	Lindsay Walton Front-end Developer	[email protected]	Member
2	Courtney Henry Designer	[email protected]	Admin
3	Tom Cook Director of Product	[email protected]	Member
4	Whitney Francis Copywriter	[email protected]	Admin
5	Leonard Krasner Senior Designer	[email protected]	Owner
6	Floyd Miles Principal Designer	[email protected]	Member

Expandir código

API

Props

Slots

Expose

Você pode acessar a instância tipada do componente usando useTemplateRef.

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

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

Isso dará a você acesso ao seguinte:

Tema

export default defineAppConfig({
  ui: {
    table: {
      slots: {
        root: 'relative overflow-auto outline-accent/25 focus-visible:outline-3',
        base: 'min-w-full overflow-clip',
        caption: 'sr-only',
        thead: 'relative',
        tbody: 'isolate [&>tr[data-selectable=true]:hover>td]:bg-neutral-100 [&>tr]:data-[selectable=true]:focus-visible:outline-accent [&>tr:nth-child(even)>td]:bg-neutral-50',
        tfoot: 'relative',
        tr: 'data-[selected=true]:bg-accented',
        th: 'px-8 py-3.5 text-lg text-secondary text-left rtl:text-right font-semibold data-[sortable=true]:px-4 bg-clip-padding',
        td: 'px-8 py-4 text-base whitespace-nowrap not-last:border-r border-default bg-clip-padding',
        empty: 'py-6 text-center text-sm text-muted',
        loading: 'py-6 text-center'
      },
      variants: {
        pinned: {
          true: {
            th: 'sticky bg-default z-1',
            td: 'sticky bg-default z-1'
          }
        },
        sticky: {
          true: {
            thead: 'sticky top-0 inset-x-0 bg-default z-1',
            tfoot: 'sticky bottom-0 inset-x-0 bg-default z-1'
          },
          header: {
            thead: 'sticky top-0 inset-x-0 bg-default z-1'
          },
          footer: {
            tfoot: 'sticky bottom-0 inset-x-0 bg-default z-1'
          }
        },
        loading: {
          true: {
            thead: 'after:absolute after:z-1 after:h-px'
          }
        },
        empty: {
          true: {
            thead: 'hidden',
            tfoot: 'hidden'
          }
        },
        externalScroll: {
          true: {
            root: 'overflow-visible'
          }
        },
        loadingAnimation: {
          carousel: '',
          'carousel-inverse': '',
          swing: '',
          elastic: ''
        },
        loadingColor: {
          primary: '',
          secondary: '',
          accent: '',
          success: '',
          info: '',
          warning: '',
          error: '',
          neutral: ''
        }
      },
      compoundVariants: [
        {
          loading: true,
          loadingColor: 'primary',
          class: {
            thead: 'after:bg-primary'
          }
        },
        {
          loading: true,
          loadingColor: 'neutral',
          class: {
            thead: 'after:bg-inverted'
          }
        },
        {
          loading: true,
          loadingAnimation: 'carousel',
          class: {
            thead: 'after:animate-[carousel_2s_ease-in-out_infinite] rtl:after:animate-[carousel-rtl_2s_ease-in-out_infinite]'
          }
        },
        {
          loading: true,
          loadingAnimation: 'carousel-inverse',
          class: {
            thead: 'after:animate-[carousel-inverse_2s_ease-in-out_infinite] rtl:after:animate-[carousel-inverse-rtl_2s_ease-in-out_infinite]'
          }
        },
        {
          loading: true,
          loadingAnimation: 'swing',
          class: {
            thead: 'after:animate-[swing_2s_ease-in-out_infinite]'
          }
        },
        {
          loading: true,
          loadingAnimation: 'elastic',
          class: {
            thead: 'after:animate-[elastic_2s_ease-in-out_infinite]'
          }
        }
      ],
      defaultVariants: {
        loadingColor: 'accent',
        loadingAnimation: 'carousel'
      }
    }
  }
})

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      ui: {
        table: {
          slots: {
            root: 'relative overflow-auto outline-accent/25 focus-visible:outline-3',
            base: 'min-w-full overflow-clip',
            caption: 'sr-only',
            thead: 'relative',
            tbody: 'isolate [&>tr[data-selectable=true]:hover>td]:bg-neutral-100 [&>tr]:data-[selectable=true]:focus-visible:outline-accent [&>tr:nth-child(even)>td]:bg-neutral-50',
            tfoot: 'relative',
            tr: 'data-[selected=true]:bg-accented',
            th: 'px-8 py-3.5 text-lg text-secondary text-left rtl:text-right font-semibold data-[sortable=true]:px-4 bg-clip-padding',
            td: 'px-8 py-4 text-base whitespace-nowrap not-last:border-r border-default bg-clip-padding',
            empty: 'py-6 text-center text-sm text-muted',
            loading: 'py-6 text-center'
          },
          variants: {
            pinned: {
              true: {
                th: 'sticky bg-default z-1',
                td: 'sticky bg-default z-1'
              }
            },
            sticky: {
              true: {
                thead: 'sticky top-0 inset-x-0 bg-default z-1',
                tfoot: 'sticky bottom-0 inset-x-0 bg-default z-1'
              },
              header: {
                thead: 'sticky top-0 inset-x-0 bg-default z-1'
              },
              footer: {
                tfoot: 'sticky bottom-0 inset-x-0 bg-default z-1'
              }
            },
            loading: {
              true: {
                thead: 'after:absolute after:z-1 after:h-px'
              }
            },
            empty: {
              true: {
                thead: 'hidden',
                tfoot: 'hidden'
              }
            },
            externalScroll: {
              true: {
                root: 'overflow-visible'
              }
            },
            loadingAnimation: {
              carousel: '',
              'carousel-inverse': '',
              swing: '',
              elastic: ''
            },
            loadingColor: {
              primary: '',
              secondary: '',
              accent: '',
              success: '',
              info: '',
              warning: '',
              error: '',
              neutral: ''
            }
          },
          compoundVariants: [
            {
              loading: true,
              loadingColor: 'primary',
              class: {
                thead: 'after:bg-primary'
              }
            },
            {
              loading: true,
              loadingColor: 'neutral',
              class: {
                thead: 'after:bg-inverted'
              }
            },
            {
              loading: true,
              loadingAnimation: 'carousel',
              class: {
                thead: 'after:animate-[carousel_2s_ease-in-out_infinite] rtl:after:animate-[carousel-rtl_2s_ease-in-out_infinite]'
              }
            },
            {
              loading: true,
              loadingAnimation: 'carousel-inverse',
              class: {
                thead: 'after:animate-[carousel-inverse_2s_ease-in-out_infinite] rtl:after:animate-[carousel-inverse-rtl_2s_ease-in-out_infinite]'
              }
            },
            {
              loading: true,
              loadingAnimation: 'swing',
              class: {
                thead: 'after:animate-[swing_2s_ease-in-out_infinite]'
              }
            },
            {
              loading: true,
              loadingAnimation: 'elastic',
              class: {
                thead: 'after:animate-[elastic_2s_ease-in-out_infinite]'
              }
            }
          ],
          defaultVariants: {
            loadingColor: 'accent',
            loadingAnimation: 'carousel'
          }
        }
      }
    })
  ]
})

Changelog