diff --git a/apps/www/src/content/docs/components/data-table.md b/apps/www/src/content/docs/components/data-table.md index 9e50d6fa..cec3a907 100644 --- a/apps/www/src/content/docs/components/data-table.md +++ b/apps/www/src/content/docs/components/data-table.md @@ -20,4 +20,1139 @@ We'll start with the basic `` component and build a complex data table **Tip:** If you find yourself using the same table in multiple places in your app, you can always extract it into a reusable component. - \ No newline at end of file + + +## Table of Contents + +This guide will show you how to use [TanStack Table](https://tanstack.com/table/v8) and the
component to build your own custom data table. We'll cover the following topics: + +- [Basic Table](#basic-table) +- [Row Actions](#row-actions) +- [Pagination](#pagination) +- [Sorting](#sorting) +- [Filtering](#filtering) +- [Visibility](#visibility) +- [Row Selection](#row-selection) +- [Reusable Components](#reusable-components) + +## Installation + +1. Add the `
` component to your project: + +```bash +npx shadcn-vue@latest add table +``` + +2. Add `tanstack/vue-table` dependency: + +```bash +npm install @tanstack/vue-table +``` + +## Prerequisites + +We are going to build a table to show recent payments. Here's what our data looks like: + +```ts:line-numbers +interface Payment { + id: string + amount: number + status: 'pending' | 'processing' | 'success' | 'failed' + email: string +} + +export const payments: Payment[] = [ + { + id: '728ed52f', + amount: 100, + status: 'pending', + email: 'm@example.com', + }, + { + id: '489e1d42', + amount: 125, + status: 'processing', + email: 'example@gmail.com', + }, + // ... +] +``` + +## Project Structure + +Start by creating the following file structure: + +```txt + components + └── payments + ├── columns.ts + ├── data-table.vue + ├── data-table-dropdown.vue +└── app.vue +``` + +I'm using a Nuxt.js example here but this works for any other Vue framework. + +- `columns.ts` It will contain our column definitions. +- `data-table.vue` It will contain our `` component. +- `data-table-dropdown.vue` It will contain our `` component. +- `app.vue` This is where we'll fetch data and render our table. + +## Basic Table + +Let's start by building a basic table. + + + +### Column Definitions + +First, we'll define our columns in the `columns.ts` file. + +```ts:line-numbers title="components/payments/columns.ts" {1,12-27} +import type { ColumnDef } from '@tanstack/vue-table' + +// This type is used to define the shape of our data. +// You can use a Zod schema here if you want. +export interface Payment { + id: string + amount: number + status: 'pending' | 'processing' | 'success' | 'failed' + email: string +} + +export const columns: ColumnDef[] = [ + { + accessorKey: 'status', + header: 'Status', + }, + { + accessorKey: 'email', + header: 'Email', + }, + { + accessorKey: 'amount', + header: 'Amount', + }, +] +``` + + + +**Note:** Columns are where you define the core of what your table +will look like. They define the data that will be displayed, how it will be +formatted, sorted and filtered. + + + +### `` component + +Next, we'll create a `` component to render our table. + +```ts:line-numbers + + + +``` + + + +**Tip**: If you find yourself using `` in multiple places, this is the component you could make reusable by extracting it to `components/ui/data-table.vue`. + +`` + + + + +### Render the table + +Finally, we'll render our table in our index component. + +```ts:line-numbers showLineNumbers{28} + + + +``` + + + +## Cell Formatting + +Let's format the amount cell to display the dollar amount. We'll also align the cell to the right. + + + +### Update columns definition + +Update the `header` and `cell` definitions for amount as follows: + + +```ts:line-numbers showLineNumbers title="components/payments/columns.ts" {5-17} +import { h } from 'vue' + +export const columns: ColumnDef[] = [ + { + accessorKey: "amount", + header: () => h('div', { class: 'text-right' }, 'Amount'), + cell: ({ row }) => { + const amount = parseFloat(row.getValue("amount")) + const formatted = new Intl.NumberFormat("en-US", { + style: "currency", + currency: "USD", + }).format(amount) + + return h('div', { class: 'text-right font-medium' }, formatted) + }, + } +] +``` +You can use the same approach to format other cells and headers. + + +## Row Actions + +Let's add row actions to our table. We'll use a `` component for this. + + + +### Add the following into your `DataTableDropDown.vue` component: + +```ts:line-numbers +// DataTableDropDown.vue + + + + +``` + +### Update columns definition + +Update our columns definition to add a new `actions` column. The `actions` cell returns a `` component. + + +```ts:line-numbers showLineNumber{2,6-16} +import { ColumnDef } from "@tanstack/vue-table" +import DropdownAction from '@/components/DataTableDropDown.vue' + +export const columns: ColumnDef[] = [ + // ... + { + id: 'actions', + enableHiding: false, + cell: ({ row }) => { + const payment = row.original + + return h('div', { class: 'relative' }, h(DropdownAction, { + payment, + })) + }, + }, +] + +``` + +You can access the row data using `row.original` in the `cell` function. Use this to handle actions for your row eg. use the `id` to make a DELETE call to your API. + + + +## Pagination + +Next, we'll add pagination to our table. + + + +### Update `` + +```ts:line-numbers showLineNumbers{4,12} +import { + FlexRender, + getCoreRowModel, + getPaginationRowModel, + useVueTable, +} from "@tanstack/vue-table" + +const table = useVueTable({ + data: props.data, + columns: props.columns, + getCoreRowModel: getCoreRowModel(), + getPaginationRowModel: getPaginationRowModel(), +}) +``` + +This will automatically paginate your rows into pages of 10. See the [pagination docs](https://tanstack.com/table/v8/docs/api/features/pagination) for more information on customizing page size and implementing manual pagination. + +### Add pagination controls + +We can add pagination controls to our table using the `