Skip to Content
Documentation
Bien démarrer

Démarrage Vue et Nuxt

Une table Vue native complète, un client Query partagé et l’intégration Nuxt.

Construisez la même table produits avec une configuration Vue native et un client Vue Query partagé. Installez le registre Vue avant de copier ces fichiers. Les concepts expliquent le fonctionnement commun.

Structure du projet

products/
  shared/products.ts
  vue/product-config.ts
  vue/product-actions.ts
  vue/products.vue
  vue/main.ts

1. Définir les enregistrements

products.ts
export interface Product extends Record<string, unknown> {
  active: boolean;
  id: string;
  image: string;
  name: string;
  price: number;
  /** Civil dates, inclusive at both ends: the window a batch is being restocked. */
  restockFrom: string;
  restockTo: string;
  status: "draft" | "active" | "archived";
  stock: number;
  tags: string[];
  updatedAt: string;
}

export const products: Product[] = [
  {
    id: "desk",
    name: "Oak desk",
    price: 420,
    stock: 12,
    status: "active",
    active: true,
    tags: ["office", "wood"],
    image: "https://placehold.co/640x480/png?text=Oak+desk",
    restockFrom: "2026-09-14",
    restockTo: "2026-09-18",
    updatedAt: "2026-09-01T09:00:00Z",
  },
  {
    id: "lamp",
    name: "Desk lamp",
    price: 65,
    stock: 0,
    status: "draft",
    active: false,
    tags: ["office"],
    image: "https://placehold.co/640x480/png?text=Desk+lamp",
    restockFrom: "2026-09-17",
    restockTo: "2026-09-24",
    updatedAt: "2026-09-02T09:00:00Z",
  },
  {
    id: "chair",
    name: "Studio chair",
    price: 180,
    stock: 6,
    status: "active",
    active: true,
    tags: ["office", "seating"],
    image: "https://placehold.co/640x480/png?text=Studio+chair",
    restockFrom: "2026-09-23",
    restockTo: "2026-10-02",
    updatedAt: "2026-09-03T09:00:00Z",
  },
];

2. Configurer la table

product-config.ts
import { defineTableConfig } from "@/components/ui/yayaw-table-vue";

export const productConfig = defineTableConfig({
  id: "products",
  translations: { namespace: "products", keys: {} },
  columns: {
    definitions: [
      { id: "name", header: "Name", type: "text" },
      { id: "price", header: "Price", type: "number" },
      { id: "stock", header: "Stock", type: "number" },
      {
        id: "status",
        header: "Status",
        type: "select",
        options: [
          { label: "Draft", value: "draft" },
          { label: "Active", value: "active" },
          { label: "Archived", value: "archived" },
        ],
      },
    ],
    order: ["name", "price", "stock", "status"],
    visible: ["name", "price", "stock", "status"],
    mandatory: ["name"],
    sort: [{ id: "name", desc: false }],
  },
  table: {
    allowCreate: false,
    allowEdit: false,
    allowDelete: false,
    allowDuplicate: false,
    allowBulkEdit: false,
    allowBulkDelete: false,
    enableRowSelection: false,
    enableViews: false,
    syncUrl: false,
    defaultPageSize: 10,
  },
});

export const getTableConfig = (tableType: string) =>
  tableType === "products" ? productConfig : undefined;

3. Connecter les actions de liste

Cet adaptateur implémente le même contrat de requête que React. La recherche porte sur les noms, références, prix, stocks, statuts, booléens et tags. Les filtres et le tri s’appliquent avant la pagination. Le résultat contient les totaux. Les enregistrements sont fictifs et restent en mémoire.

product-actions.ts
import type { TableActions } from "@/components/ui/yayaw-table-vue/types";
import { products } from "../shared/products";
import { listRecords } from "./list-records";

export const productActions: TableActions = {
  list: (input) => listRecords(products, input),
};
export const getTableActions = (tableType: string) =>
  tableType === "products" ? productActions : undefined;

Adaptateur de liste complet

list-records.ts
import {
  compatibleListParams,
  matchesContractFilter,
  normalizeFilterEnvelope,
  recordValue,
} from "@/components/ui/yayaw-table-vue/table-contracts";

export function listRecords<T extends Record<string, unknown>>(
  rows: T[],
  input: unknown
) {
  const params = compatibleListParams(recordValue(input));
  const page = Number(params.page);
  const limit = Number(params.limit);
  const search = String(params.search).toLowerCase();
  const filters = Object.entries(recordValue(params.filters));
  const advanced = normalizeFilterEnvelope(params.advancedFilters).filters;
  const matching = rows.filter((product) => {
    const row: Record<string, unknown> = product;
    const matchesSearch =
      !search ||
      ["name", "reference", "price", "stock", "status", "active", "tags"].some(
        (key) => {
          const value = product[key];
          return (
            value !== null &&
            value !== undefined &&
            String(value).toLowerCase().includes(search)
          );
        }
      );
    const matchesColumns = filters.every(([id, value]) =>
      matchesContractFilter(row[id], {
        type: typeof row[id] === "number" ? "number" : "text",
        operator: Array.isArray(value) ? "isAnyOf" : "contains",
        values: Array.isArray(value) ? value : [value],
      })
    );
    const matchesRule = (rule: Record<string, unknown>) =>
      matchesContractFilter(row[String(rule.columnId)], rule);
    const matchesAdvanced =
      advanced.length === 0 ||
      (params.advancedFilterJoin === "or"
        ? advanced.some(matchesRule)
        : advanced.every(matchesRule));
    return matchesSearch && matchesColumns && matchesAdvanced;
  });
  const sorting = Object.entries(recordValue(params.orderBy));
  matching.sort((left, right) => {
    for (const [id, direction] of sorting) {
      const a = (left as Record<string, unknown>)[id];
      const b = (right as Record<string, unknown>)[id];
      const comparison =
        typeof a === "number" && typeof b === "number"
          ? a - b
          : String(a ?? "").localeCompare(String(b ?? ""));
      if (comparison !== 0) {
        return direction === "desc" ? -comparison : comparison;
      }
    }
    return String(left.id).localeCompare(String(right.id));
  });
  return Promise.resolve({
    // Model a server response: later store mutations must not alter cached rows.
    data: structuredClone(matching.slice((page - 1) * limit, page * limit)),
    meta: {
      pageCount: Math.max(1, Math.ceil(matching.length / limit)),
      totalCount: matching.length,
    },
  });
}

4. Afficher le composant

Agrandir ↗

Données de démonstration. Les modifications restent dans cet aperçu.

5. Installer le client Query partagé

main.ts
import { QueryClient, VueQueryPlugin } from "@tanstack/vue-query";
import { createApp } from "vue";
import Products from "./products.vue";
import "@/components/ui/yayaw-table-vue/styles.css";

const app = createApp(Products);
app.use(VueQueryPlugin, { queryClient: new QueryClient() });
app.mount("#app");

Montez Products dans un élément avec id="app", ou réutilisez le point d’entrée et le provider de votre application. Gardez les styles du registre dans l’entrée CSS de l’application. Vue n’utilise pas Nuqs.

Données locales

Pour une table entièrement locale, passez :data="products" et retirez get-table-actions. Vue applique les filtres, le tri et la pagination à ce tableau. Pour une source distante, utilisez les actions : une page serveur isolée passée comme donnée locale ne représente pas tout le jeu de données.

Nuxt et SSR

Installez VueQueryPlugin dans un plugin Nuxt avec un nouveau QueryClient par requête, et importez les styles du registre dans la configuration CSS Nuxt. Enregistrez la table dans un plugin universel (pas .client) quand elle est rendue sur le serveur. Le composant ne lit les API du navigateur (URL, localStorage, mise en page) qu’après le montage, et le serveur n’envoie aucune requête qu’il n’attend pas. Isolez les rendus personnalisés qui nécessitent le navigateur et n’utilisez initialData, initialRowCount et initialPageCount que pour la première page de l’état par défaut.

Sans server-prefetch, le serveur rend l’état de chargement de la table et le navigateur charge la première page. Avec, la table charge sa première page pendant le rendu serveur (onServerPrefetch), dans l’état dont elle part, rend les lignes dans le HTML et s’hydrate sans les recharger :

  1. Un QueryClient par requête, passé en :query-client, déshydraté dans le payload Nuxt et hydraté avant le montage de l’application. Donnez-lui un staleTime : le navigateur réutilise la page tant qu’elle est fraîche, puis la recharge comme d’habitude. Avec le staleTime: 0 par défaut, il la recharge aussitôt.

  2. L’état de départ : la vue par défaut, ou :initial-view ({ id?, config, pageIndex? }) avec table.syncUrl: false, par exemple la vue favorite de la personne ou des filtres par défaut. pageIndex (à partir de zéro) ouvre une autre page que la première. Avec la synchronisation d’URL, le serveur rend l’état sans l’URL, et l’état d’un lien s’applique au montage.

  3. Les vues enregistrées que l’hôte a déjà chargées : :initial-views, :initial-favorite-view-id et initial-views-loaded. Le gestionnaire de vues démarre chargé, avec le favori, et ne demande ni views.list ni views.getFavorite au montage.

  4. table.timeZone (un fuseau IANA), pour que le serveur formate les dates dans le fuseau de la personne plutôt que dans le sien.

plugins/vue-query.ts
// Un client par requête, sérialisé dans le payload Nuxt.
import type { DehydratedState } from "@tanstack/vue-query";
import { dehydrate, hydrate, QueryClient, VueQueryPlugin } from "@tanstack/vue-query";

export default defineNuxtPlugin((nuxtApp) => {
  const state = useState<DehydratedState | null>("vue-query");
  const queryClient = new QueryClient({
    defaultOptions: { queries: { staleTime: 30_000 } },
  });
  nuxtApp.vueApp.use(VueQueryPlugin, { queryClient });
  if (import.meta.server) {
    nuxtApp.hooks.hook("app:rendered", () => {
      state.value = dehydrate(queryClient);
    });
  }
  if (import.meta.client) {
    nuxtApp.hooks.hook("app:created", () => {
      hydrate(queryClient, state.value);
    });
  }
});
pages/orders.vue
<script setup lang="ts">
import { useQueryClient } from "@tanstack/vue-query";
import { YayawDataTable } from "@/components/ui/yayaw-table-vue";
import { orderActions } from "./order-actions";
// table: { syncUrl: false, timeZone: "Europe/Paris" }
import { orderConfig } from "./order-config";

const queryClient = useQueryClient();
// Votre propre endpoint : les vues et le favori de la personne, chargés sur le serveur.
const { data: views } = await useAsyncData("orders-views", () =>
  $fetch("/api/orders/views")
);
// Ordre d’arrivée : le favori, une vue `isDefault`, sinon des filtres par défaut.
const arrival = computed(
  () =>
    views.value?.data.find((view) => view.id === views.value?.favoriteId) ??
    views.value?.data.find((view) => view.isDefault)
);
const initialView = computed(() =>
  arrival.value
    ? { id: arrival.value.id, config: arrival.value.config }
    : { config: { columnFilters: [{ id: "owner", value: ["me"] }] } }
);
</script>

<template>
  <YayawDataTable
    :config="orderConfig"
    :get-table-actions="() => orderActions"
    :query-client="queryClient"
    table-type="orders"
    server-prefetch
    :initial-view="initialView"
    :initial-views="views?.data ?? []"
    :initial-active-view-id="arrival?.id"
    :initial-favorite-view-id="views?.favoriteId ?? null"
    initial-views-loaded
  />
</template>

L’action list s’exécute aussi sur le serveur : donnez-lui les identifiants de la requête (par exemple avec useRequestFetch()), et gardez le QueryClient de chaque requête à cette requête. Un échec côté serveur, ou une page au-delà de la dernière, rend l’état de chargement, et le navigateur charge la page.

Les catalogues de tags se chargent avec les lignes. Les calculs de pied de tableau, les compteurs de facettes, les dossiers, les tableaux Kanban serveur et les modes d’affichage fournis par des renderers (Fil, Calendrier, Graphique, Carte, Arborescence, Formulaire) se chargent dans le navigateur, juste après l’hydratation ; la préférence de glisser-déposer des colonnes et l’ordre des vues gardé par le navigateur sont lus au montage. Avec la taille de page automatique, le serveur rend defaultPageSize (ou la taille de page de la vue) ; une fois les lignes mesurées, une première page plus petite garde ses premières lignes sans requête, et une plus grande se charge.

Hors rendu serveur aussi, une page de départ que le :query-client garde fraîche (dans son staleTime) s’affiche sans requête. React n’a pas de préchargement au niveau du composant : il rend de façon synchrone, affiche initialData ou son état de chargement sur le serveur, et ses requêtes lisent nativement un cache hydraté. Consultez les données initiales server-first.

Notifications de l’application

Montez un unique Toaster de vue-sonner à la racine de l’application et importez vue-sonner/style.css si vous utilisez directement Sonner. Toutes les instances de table le partagent. Les formulaires conservent leurs erreurs de validation et de reprise près des champs.

Ajouter une fonctionnalité

La suite de la documentation est organisée par fonctionnalité. Utilisez l’onglet Vue dans les guides colonnes, formulaires, actions groupées et vues. La référence des actions explique les alias de requête et de résultat partagés avec React.

Sections du guide précédent

Vue 3 et Nuxt

Consultez le guide actuel : concepts.

Couverture fonctionnelle

Consultez le guide actuel : compatibility.

Prérequis d'exécution

Consultez le guide actuel : compatibility.

Lancer le workspace Vue

Consultez le guide actuel : installation.

Migrer depuis TanStack Table 8

Consultez le guide actuel : concepts.

Enregistrer le package

Consultez le guide actuel : installation.

Configurer une table

Consultez le guide actuel : configuration.

Densité du tableau

Consultez le guide actuel : layout.

Actions de toolbar du catalogue

Consultez le guide actuel : actions.

Connecter les actions côté serveur

Consultez le guide actuel : actions.

Champ de formulaire tablePicker

Consultez le guide actuel : table-picker.

Partager le cache Vue Query

Consultez le guide actuel : query-integration.

Construire l'item de registre shadcn-vue

Consultez le guide actuel : installation.

Correspondance React vers Vue

Consultez le guide actuel : compatibility.

Comportements communs à React et Vue

Consultez le guide actuel : compatibility.

Sélection multiple et sauvegarde inline

Consultez le guide actuel : inline-editing.

Un type de colonne dans toute l’interface

Consultez le guide actuel : columns.

Formulaires générés structurés

Consultez le guide actuel : form-layout.

Lignes regroupées

Consultez le guide actuel : grouping-calculations.

Contrôles des cartes et résultats vides

Consultez le guide actuel : gallery.

Barre de filtres optionnelle

Consultez le guide actuel : filtering.

Vues favorites personnelles

Consultez le guide actuel : views.

Consultation et activité d’une entrée

Consultez le guide actuel : record-details.