Use Handsontable in Nuxt
Handsontable DataGrid works in a Nuxt application with server-side rendering (SSR). This page explains how Handsontable behaves during SSR, and how to render the grid on the client only when you want a placeholder or a smaller server bundle.
Prerequisites
-
Nuxt 3 or Nuxt 4 project set up and running.
-
Handsontable and the Vue 3 wrapper installed:
Terminal window npm install handsontable @handsontable/vue3
How Handsontable behaves with SSR
Nuxt renders Vue components on the server before sending HTML to the browser. When it renders a <HotTable> component on the server:
- The server renders a container
<div>with no grid content. - The browser hydrates the page and mounts the grid into that container.
You can import handsontable and @handsontable/vue3, and call registerAllModules(), in server code. Handsontable does not need <ClientOnly> or a .client.vue file to run in Nuxt.
Render the grid on the client only
Rendering the grid on the client only is optional. Use it when you want a placeholder in the server-rendered HTML, or when you want to keep the grid out of the server bundle.
Using <ClientOnly>
Nuxt’s built-in <ClientOnly> component prevents its children from rendering on the server. Wrap your <HotTable> in it:
<template> <ClientOnly> <HotTable :settings="gridSettings" /> <template #fallback> <p>Loading the data grid...</p> </template> </ClientOnly></template>
<script setup lang="ts">import { ref } from 'vue';import { HotTable } from '@handsontable/vue3';import { registerAllModules } from 'handsontable/registry';import type { GridSettings } from 'handsontable/settings';
registerAllModules();
const gridSettings = ref<GridSettings>({ data: [ ['Mercedes', 'Germany', 2000, 2023], ['BMW', 'Germany', 1998, 2024], ['Toyota', 'Japan', 2001, 2023], ['Honda', 'Japan', 1999, 2022], ['Ford', 'USA', 1997, 2024], ], colHeaders: ['Brand', 'Country', 'Since', 'Until'], rowHeaders: true, // licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/});</script>The #fallback slot renders on the server in place of the grid. Use it to show a placeholder or skeleton so the page has visible content before the browser takes over.
Using the .client.vue suffix
Nuxt treats any component file ending in .client.vue as a client-only component. It is excluded from the server bundle entirely, including its imports. Use it when you want to keep all Handsontable code out of the server bundle.
Create a wrapper component named with the .client.vue suffix:
components/└── HandsonGrid.client.vue<template> <HotTable :settings="props.settings" /></template>
<script setup lang="ts">import { HotTable } from '@handsontable/vue3';import { registerAllModules } from 'handsontable/registry';import type { GridSettings } from 'handsontable/settings';
registerAllModules();
const props = defineProps<{ settings: GridSettings;}>();</script>Use it in your page without any additional wrapper:
<template> <HandsonGrid :settings="gridSettings" /></template>
<script setup lang="ts">import { ref } from 'vue';import type { GridSettings } from 'handsontable/settings';
const gridSettings = ref<GridSettings>({ data: [ ['Mercedes', 'Germany', 2000, 2023], ['BMW', 'Germany', 1998, 2024], ['Toyota', 'Japan', 2001, 2023], ['Honda', 'Japan', 1999, 2022], ['Ford', 'USA', 1997, 2024], ], colHeaders: ['Brand', 'Country', 'Since', 'Until'], rowHeaders: true, // licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/});</script>nuxt.config.ts notes
For most Nuxt projects, no extra configuration is needed.
In rare cases, for example when a Nuxt plugin imports Handsontable in a server-side context and your build fails to resolve the packages, you can add them to build.transpile as a fallback:
export default defineNuxtConfig({ build: { transpile: ['handsontable', '@handsontable/vue3'], },});Try the default setup before you reach for this option.
Result
Handsontable renders in the browser. The SSR pass renders a container with no grid content, the #fallback content (with <ClientOnly>), or nothing (with .client.vue). The grid initializes once the Vue component mounts on the client.