@toolbox-web/grid-vue

@toolbox-web/grid-vue

Vue 3 adapter for @toolbox-web/grid data grid component. Provides components and composables for declarative Vue integration with custom cell renderers and editors.

Features

• ✅ Full Vue 3 integration - Use Vue components for cell renderers and editors
• ✅ Composition API - Built with <script setup> and TypeScript generics
• ✅ Declarative feature props - Enable plugins with simple props like selection="range"
• ✅ Tree-shakeable features - Only import the features you use
• ✅ Slot-based customization - #cell and #editor slots for custom rendering
• ✅ Type-level defaults - App-wide renderers/editors via GridTypeProvider
• ✅ Icon configuration - App-wide icon overrides via GridProvider or GridIconProvider
• ✅ Composables - useGrid for programmatic access
• ✅ Master-detail - TbwGridDetailPanel for expandable rows
• ✅ Tool panels - TbwGridToolPanel for custom sidebar content
• ✅ Responsive cards - TbwGridResponsiveCard for mobile layouts
• ✅ Full type safety - TypeScript generics support
• ✅ Vue 3.4+ - Supports defineModel and improved generics

Installation

# npm
npm install @toolbox-web/grid @toolbox-web/grid-vue

# yarn
yarn add @toolbox-web/grid @toolbox-web/grid-vue

# pnpm
pnpm add @toolbox-web/grid @toolbox-web/grid-vue

# bun
bun add @toolbox-web/grid @toolbox-web/grid-vue

Quick Start

1. Register the Grid Component

In your application entry point, import the grid registration:

// main.ts
import '@toolbox-web/grid';

2. Use in Components

<script setup lang="ts">
import { TbwGrid, TbwGridColumn } from '@toolbox-web/grid-vue';
import { ref } from 'vue';

interface Employee {
  id: number;
  name: string;
  department: string;
  salary: number;
}

const employees = ref<Employee[]>([
  { id: 1, name: 'Alice', department: 'Engineering', salary: 95000 },
  { id: 2, name: 'Bob', department: 'Marketing', salary: 75000 },
  { id: 3, name: 'Charlie', department: 'Sales', salary: 85000 },
]);
</script>

<template>
  <TbwGrid :rows="employees">
    <TbwGridColumn field="id" header="ID" :width="60" />
    <TbwGridColumn field="name" header="Name" :sortable="true" />
    <TbwGridColumn field="department" header="Department" :sortable="true" />
    <TbwGridColumn field="salary" header="Salary" type="number" />
  </TbwGrid>
</template>

TbwGrid Props

Enabling Features

Features are enabled using declarative props with side-effect imports. This gives you the best of both worlds: clean, intuitive templates and tree-shakeable bundles.

How It Works

1. Import the feature - A side-effect import registers the feature factory
2. Use the prop - TbwGrid detects the prop and creates the plugin instance

<script setup lang="ts">
import { TbwGrid } from '@toolbox-web/grid-vue';

// 1. Import features you need (once, typically in main.ts or the component file)
import '@toolbox-web/grid-vue/features/selection';
import '@toolbox-web/grid-vue/features/multi-sort';
import '@toolbox-web/grid-vue/features/filtering';
</script>

<template>
  <!-- 2. Use declarative props - no manual plugin instantiation! -->
  <TbwGrid :rows="employees" :columns="columns" selection="range" multi-sort filtering />
</template>

Why Side-Effect Imports?

• Tree-shakeable - Only the features you import are bundled
• Synchronous - No loading states, no HTTP requests, no spinners
• Type-safe - Full TypeScript support for feature props
• Clean templates - No plugins: [new SelectionPlugin({ mode: 'range' })] boilerplate

Available Features

Import from @toolbox-web/grid-vue/features/<name>:

Import All Features

For prototyping or when bundle size isn't critical, import all features at once:

// Import all features (larger bundle)
import '@toolbox-web/grid-vue/features';

Custom Cell Renderers

Use the #cell slot on TbwGridColumn for custom rendering. Type the column with your row shape via the generic <TbwGridColumn<Employee>> syntax — slot props (row, value) then narrow automatically with no per-template annotation needed:

<script setup lang="ts">
import { TbwGrid, TbwGridColumn } from '@toolbox-web/grid-vue';
import StatusBadge from './StatusBadge.vue';
interface Employee {
  id: string;
  name: string;
  status: 'active' | 'inactive';
}
</script>

<template>
  <TbwGrid<Employee> :rows="employees">
    <TbwGridColumn<Employee> field="name" header="Name" />
    <TbwGridColumn<Employee> field="status" header="Status">
      <template #cell="{ value, row }">
        <!-- row: Employee, value: any (per-column) -->
        <StatusBadge :status="value" :employee="row" />
      </template>
    </TbwGridColumn>
  </TbwGrid>
</template>

If you also know the value type, pass both generics: <TbwGridColumn<Employee, string>> (or annotate the slot prop with CellSlotProps<Employee, string>).

Slot Props

The #cell slot receives:

Generic defaults: CellSlotProps<TRow = unknown, TValue = any> and TbwGridColumn<TRow = unknown, TValue = any>. Specify TRow on the column (e.g. <TbwGridColumn<Employee>>) and slot props inherit it automatically; TValue defaults to any because the value shape is per-column and awkward to narrow inside template expressions.

Custom Cell Editors

Use the #editor slot for inline editing. Same generic-typing pattern as #cell:

<script setup lang="ts">
import { TbwGrid, TbwGridColumn } from '@toolbox-web/grid-vue';
import '@toolbox-web/grid-vue/features/editing';
</script>

<template>
  <TbwGrid<Employee> :rows="employees" editing="dblclick">
    <TbwGridColumn<Employee> field="status" header="Status" :editable="true">
      <template #editor="{ value, commit, cancel }">
        <!-- value: any, commit: (newValue: any) => void -->
        <select :value="value" @change="(e) => commit((e.target as HTMLSelectElement).value)">
          <option value="active">Active</option>
          <option value="inactive">Inactive</option>
        </select>
      </template>
    </TbwGridColumn>
  </TbwGrid>
</template>

Editor Slot Props

Generic defaults: EditorSlotProps<TRow = unknown, TValue = any> — same rationale as CellSlotProps above. Specify TRow for row-shape safety; pass TValue when you know the column's value type.

Events

Handle grid events using Vue's template syntax.

Template Event Binding

<script setup lang="ts">
import { TbwGrid } from '@toolbox-web/grid-vue';
import type { CellClickDetail, SortChangeDetail } from '@toolbox-web/grid';

function onCellClick(e: CustomEvent<CellClickDetail>) {
  console.log(`Clicked ${e.detail.field} at row ${e.detail.rowIndex}`);
}

function onSortChange(e: CustomEvent<SortChangeDetail>) {
  console.log(`Sorted by ${e.detail.field} ${e.detail.direction}`);
}
</script>

<template>
  <TbwGrid :rows="rows" @cell-click="onCellClick" @sort-change="onSortChange">
    <TbwGridColumn field="name" header="Name" sortable />
  </TbwGrid>
</template>

Available Events

Using Plugins (Advanced)

For full control, pass plugin instances directly via :grid-config. Use markRaw() to prevent Vue from making plugin instances reactive:

<script setup lang="ts">
import { markRaw } from 'vue';
import { TbwGrid, TbwGridColumn } from '@toolbox-web/grid-vue';
import { SelectionPlugin } from '@toolbox-web/grid/plugins/selection';
import { FilteringPlugin } from '@toolbox-web/grid/plugins/filtering';

const gridConfig = {
  plugins: markRaw([new SelectionPlugin({ mode: 'range' }), new FilteringPlugin({ debounceMs: 200 })]),
};
</script>

<template>
  <TbwGrid :rows="rows" :grid-config="gridConfig">
    <TbwGridColumn field="name" header="Name" />
  </TbwGrid>
</template>

Important: Always wrap plugin arrays with markRaw(). Vue's reactivity proxy breaks plugin internal state.

You can also pass plugins through the dedicated :plugins prop, matching <DataGrid plugins={...}> in React and [plugins] in Angular. When :plugins is set, feature props are ignored — the array is the full plugin list:

<script setup lang="ts">
import { markRaw } from 'vue';
import { SelectionPlugin } from '@toolbox-web/grid/plugins/selection';

const plugins = markRaw([new SelectionPlugin({ mode: 'range' })]);
</script>

<template>
  <TbwGrid :rows="rows" :plugins="plugins" />
</template>

Composables

useGrid

Access grid methods and state programmatically:

<script setup lang="ts">
import { useGrid } from '@toolbox-web/grid-vue';

const {
  isReady,
  config,
  forceLayout,
  getConfig,
  ready,
  getPlugin,
  toggleGroup,
  registerStyles,
  unregisterStyles,
  getVisibleColumns,
} = useGrid();
</script>

Providers

GridTypeProvider

Define app-wide type renderers:

<script setup lang="ts">
import { GridTypeProvider, type TypeDefaultsMap } from '@toolbox-web/grid-vue';
import { h } from 'vue';
import CurrencyCell from './CurrencyCell.vue';

const typeDefaults: TypeDefaultsMap = {
  currency: {
    renderer: (ctx) => h(CurrencyCell, { value: ctx.value }),
  },
  percentage: {
    renderer: (ctx) => h('span', `${(ctx.value * 100).toFixed(1)}%`),
  },
};
</script>

<template>
  <GridTypeProvider :defaults="typeDefaults">
    <App />
  </GridTypeProvider>
</template>

Then use in columns:

<TbwGridColumn field="salary" header="Salary" type="currency" />

GridIconProvider

Override grid icons app-wide:

<script setup lang="ts">
import { GridIconProvider } from '@toolbox-web/grid-vue';

const icons = {
  sortAsc: '↑',
  sortDesc: '↓',
  expand: '+',
  collapse: '−',
  filter: '🔍',
};
</script>

<template>
  <GridIconProvider :icons="icons">
    <App />
  </GridIconProvider>
</template>

GridProvider

Combined provider for both types and icons:

<script setup lang="ts">
import { GridProvider } from '@toolbox-web/grid-vue';
</script>

<template>
  <GridProvider :type-defaults="typeDefaults" :icons="icons">
    <App />
  </GridProvider>
</template>

Master-Detail

Expandable row details:

<script setup lang="ts">
import { TbwGrid, TbwGridDetailPanel, type DetailPanelContext } from '@toolbox-web/grid-vue';
import '@toolbox-web/grid-vue/features/master-detail';
</script>

<template>
  <TbwGrid :rows="employees" master-detail>
    <TbwGridColumn field="name" header="Name" />
    <TbwGridColumn field="department" header="Department" />

    <TbwGridDetailPanel v-slot="{ row }: DetailPanelContext<Employee>">
      <div class="detail-content">
        <h4>{{ row.name }}</h4>
        <p>Department: {{ row.department }}</p>
        <p>Email: {{ row.email }}</p>
      </div>
    </TbwGridDetailPanel>
  </TbwGrid>
</template>

Tool Panels

Custom sidebar panels:

<script setup lang="ts">
import { TbwGrid, TbwGridToolPanel, type ToolPanelContext } from '@toolbox-web/grid-vue';
</script>

<template>
  <TbwGrid :rows="employees">
    <TbwGridColumn field="name" header="Name" />

    <TbwGridToolPanel id="stats" title="Statistics" v-slot="{ rows }: ToolPanelContext<Employee>">
      <div class="stats-panel">
        <p>Total: {{ rows.length }}</p>
        <p>Avg Salary: {{ averageSalary(rows) }}</p>
      </div>
    </TbwGridToolPanel>
  </TbwGrid>
</template>

Responsive Cards

Mobile-friendly card layout:

<script setup lang="ts">
import { TbwGrid, TbwGridResponsiveCard, type ResponsiveCardContext } from '@toolbox-web/grid-vue';
import '@toolbox-web/grid-vue/features/responsive';
</script>

<template>
  <TbwGrid :rows="employees" responsive>
    <TbwGridColumn field="name" header="Name" />
    <TbwGridColumn field="department" header="Department" />

    <TbwGridResponsiveCard v-slot="{ row }: ResponsiveCardContext<Employee>">
      <div class="employee-card">
        <h3>{{ row.name }}</h3>
        <p>{{ row.department }}</p>
      </div>
    </TbwGridResponsiveCard>
  </TbwGrid>
</template>

TypeScript Support

Full generic support for row types:

<script setup lang="ts" generic="T extends Employee">
import { TbwGrid, TbwGridColumn } from '@toolbox-web/grid-vue';

interface Employee {
  id: number;
  name: string;
  salary: number;
}

const props = defineProps<{
  employees: T[];
}>();
</script>

<template>
  <TbwGrid :rows="props.employees">
    <TbwGridColumn field="name" header="Name" />
    <TbwGridColumn field="salary" header="Salary">
      <template #cell="{ value }"> ${{ value.toLocaleString() }} </template>
    </TbwGridColumn>
  </TbwGrid>
</template>

API Reference

Components

Composables

Types

Requirements

• Vue 3.4+ (uses defineModel and improved generics)
• @toolbox-web/grid (peer dependency)

Demo

See the Vue demo app for a full-featured example using @toolbox-web/grid-vue.

bun nx serve demo-vue

Building

bun nx build grid-vue

Running Tests

bun nx test grid-vue

License

MIT © Øystein Amundsen