@gp-grid/vue

@gp-grid/vue 🏁 🏎️

Logo by camillo18tre ❤️

🎮 Demo • 📖 Documentation •

A high-performance, feature lean Vue 3 data grid component built to manage grids with huge amount (millions) of rows. It's based on its core dependency: @gp-grid/core, featuring virtual scrolling, cell selection, sorting, filtering, editing, and Excel-like fill handle.

Table of Contents

• Features
• Installation
• Quick Start
• Examples
• API Reference
• Keyboard Shortcuts
• Styling
• Donations

Features

• Virtual Scrolling: Efficiently handles 150,000+ rows through slot-based recycling
• Cell Selection: Single cell, range selection, Shift+click extend, Ctrl+click toggle
• Multi-Column Sorting: Click to sort, Shift+click for multi-column sort
• Column Filtering: Built-in filter row with debounced input
• Cell Editing: Double-click or press Enter to edit, with custom editor support
• Fill Handle: Excel-like drag-to-fill for editable cells
• Keyboard Navigation: Arrow keys, Tab, Enter, Escape, Ctrl+A, Ctrl+C, Ctrl+V
• Custom Renderers: Registry-based cell, edit, and header renderers
• Dark Mode: Built-in dark theme support
• TypeScript: Full type safety with exported types

Installation

Use npm, yarn or pnpm

pnpm add @gp-grid/vue

Quick Start

<script setup lang="ts">
import { GpGrid, type ColumnDefinition } from "@gp-grid/vue";

interface Person {
  id: number;
  name: string;
  age: number;
  email: string;
}

const columns: ColumnDefinition[] = [
  { field: "id", cellDataType: "number", width: 80, headerName: "ID" },
  { field: "name", cellDataType: "text", width: 150, headerName: "Name" },
  { field: "age", cellDataType: "number", width: 80, headerName: "Age" },
  { field: "email", cellDataType: "text", width: 250, headerName: "Email" },
];

const data: Person[] = [
  { id: 1, name: "Alice", age: 30, email: "alice@example.com" },
  { id: 2, name: "Bob", age: 25, email: "bob@example.com" },
  { id: 3, name: "Charlie", age: 35, email: "charlie@example.com" },
];
</script>

<template>
  <div style="width: 800px; height: 400px">
    <GpGrid :columns="columns" :row-data="data" :row-height="36" />
  </div>
</template>

Examples

Client-Side Data Source with Sorting and Filtering

For larger datasets with client-side sort/filter operations:

<script setup lang="ts">
import { computed } from "vue";
import {
  GpGrid,
  createClientDataSource,
  type ColumnDefinition,
} from "@gp-grid/vue";

interface Product {
  id: number;
  name: string;
  price: number;
  category: string;
}

const columns: ColumnDefinition[] = [
  { field: "id", cellDataType: "number", width: 80, headerName: "ID" },
  { field: "name", cellDataType: "text", width: 200, headerName: "Product" },
  { field: "price", cellDataType: "number", width: 100, headerName: "Price" },
  {
    field: "category",
    cellDataType: "text",
    width: 150,
    headerName: "Category",
  },
];

const products = computed<Product[]>(() =>
  Array.from({ length: 10000 }, (_, i) => ({
    id: i + 1,
    name: `Product ${i + 1}`,
    price: Math.round(Math.random() * 1000) / 10,
    category: ["Electronics", "Clothing", "Food", "Books"][i % 4],
  })),
);

const dataSource = computed(() => createClientDataSource(products.value));
</script>

<template>
  <div style="width: 100%; height: 500px">
    <GpGrid
      :columns="columns"
      :data-source="dataSource"
      :row-height="36"
      :header-height="40"
    />
  </div>
</template>

Server-Side Data Source

For datasets too large to load entirely in memory, use a server-side data source:

<script setup lang="ts">
import { computed } from "vue";
import {
  GpGrid,
  createServerDataSource,
  type ColumnDefinition,
  type DataSourceRequest,
  type DataSourceResponse,
} from "@gp-grid/vue";

interface User {
  id: number;
  name: string;
  email: string;
  role: string;
  createdAt: string;
}

const columns: ColumnDefinition[] = [
  { field: "id", cellDataType: "number", width: 80, headerName: "ID" },
  { field: "name", cellDataType: "text", width: 150, headerName: "Name" },
  { field: "email", cellDataType: "text", width: 250, headerName: "Email" },
  { field: "role", cellDataType: "text", width: 120, headerName: "Role" },
  {
    field: "createdAt",
    cellDataType: "dateString",
    width: 150,
    headerName: "Created",
  },
];

// API fetch function that handles pagination, sorting, and filtering
async function fetchUsers(
  request: DataSourceRequest,
): Promise<DataSourceResponse<User>> {
  const { pagination, sort, filter } = request;

  // Build query parameters
  const params = new URLSearchParams({
    page: String(pagination.pageIndex),
    limit: String(pagination.pageSize),
  });

  // Add sorting parameters
  if (sort && sort.length > 0) {
    // Format: sortBy=name:asc,email:desc
    const sortString = sort.map((s) => `${s.colId}:${s.direction}`).join(",");
    params.set("sortBy", sortString);
  }

  // Add filter parameters
  if (filter) {
    Object.entries(filter).forEach(([field, value]) => {
      if (value) {
        params.set(`filter[${field}]`, String(value));
      }
    });
  }

  // Make API request
  const response = await fetch(`https://api.example.com/users?${params}`);

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  const data = await response.json();

  // Return in DataSourceResponse format
  return {
    rows: data.users, // Array of User objects
    totalRows: data.total, // Total count for virtual scrolling
  };
}

// Create server data source - computed to prevent recreation
const dataSource = computed(() => createServerDataSource<User>(fetchUsers));
</script>

<template>
  <div style="width: 100%; height: 600px">
    <GpGrid
      :columns="columns"
      :data-source="dataSource"
      :row-height="36"
      :header-height="40"
      :dark-mode="true"
    />
  </div>
</template>

Custom Cell Renderers

Use the registry pattern to define reusable renderers:

<script setup lang="ts">
import { h } from "vue";
import {
  GpGrid,
  type ColumnDefinition,
  type CellRendererParams,
  type VueCellRenderer,
} from "@gp-grid/vue";

interface Order {
  id: number;
  customer: string;
  total: number;
  status: "pending" | "shipped" | "delivered" | "cancelled";
}

// Define reusable renderers
const cellRenderers: Record<string, VueCellRenderer> = {
  // Currency formatter
  currency: (params: CellRendererParams) => {
    const value = params.value as number;
    return h(
      "span",
      { style: { color: "#047857", fontWeight: 600 } },
      `$${value.toLocaleString("en-US", { minimumFractionDigits: 2 })}`,
    );
  },

  // Status badge
  statusBadge: (params: CellRendererParams) => {
    const status = params.value as Order["status"];
    const colors: Record<string, { bg: string; text: string }> = {
      pending: { bg: "#fef3c7", text: "#92400e" },
      shipped: { bg: "#dbeafe", text: "#1e40af" },
      delivered: { bg: "#dcfce7", text: "#166534" },
      cancelled: { bg: "#fee2e2", text: "#991b1b" },
    };
    const color = colors[status] ?? { bg: "#f3f4f6", text: "#374151" };

    return h(
      "span",
      {
        style: {
          backgroundColor: color.bg,
          color: color.text,
          padding: "2px 8px",
          borderRadius: "12px",
          fontSize: "12px",
          fontWeight: 600,
        },
      },
      status.toUpperCase(),
    );
  },

  // Bold text
  bold: (params: CellRendererParams) => h("strong", String(params.value ?? "")),
};

const columns: ColumnDefinition[] = [
  {
    field: "id",
    cellDataType: "number",
    width: 80,
    headerName: "ID",
    cellRenderer: "bold",
  },
  {
    field: "customer",
    cellDataType: "text",
    width: 200,
    headerName: "Customer",
  },
  {
    field: "total",
    cellDataType: "number",
    width: 120,
    headerName: "Total",
    cellRenderer: "currency",
  },
  {
    field: "status",
    cellDataType: "text",
    width: 120,
    headerName: "Status",
    cellRenderer: "statusBadge",
  },
];

const orders: Order[] = [
  { id: 1, customer: "Acme Corp", total: 1250.0, status: "shipped" },
  { id: 2, customer: "Globex Inc", total: 890.5, status: "pending" },
  { id: 3, customer: "Initech", total: 2100.75, status: "delivered" },
];
</script>

<template>
  <div style="width: 100%; height: 400px">
    <GpGrid
      :columns="columns"
      :row-data="orders"
      :row-height="40"
      :cell-renderers="cellRenderers"
    />
  </div>
</template>

Editable Cells with Custom Editors

<script setup lang="ts">
import { h, ref as vueRef } from "vue";
import {
  GpGrid,
  createClientDataSource,
  type ColumnDefinition,
  type EditRendererParams,
  type VueEditRenderer,
} from "@gp-grid/vue";

interface Task {
  id: number;
  title: string;
  priority: "low" | "medium" | "high";
  completed: boolean;
}

// Custom select editor for priority field
const editRenderers: Record<string, VueEditRenderer> = {
  prioritySelect: (params: EditRendererParams) => {
    return h(
      "select",
      {
        autofocus: true,
        value: params.initialValue as string,
        onChange: (e: Event) => {
          const target = e.target as HTMLSelectElement;
          params.onValueChange(target.value);
        },
        onBlur: () => params.onCommit(),
        onKeydown: (e: KeyboardEvent) => {
          if (e.key === "Enter") params.onCommit();
          if (e.key === "Escape") params.onCancel();
        },
        style: {
          width: "100%",
          height: "100%",
          border: "none",
          outline: "none",
          padding: "0 8px",
        },
      },
      [
        h("option", { value: "low" }, "Low"),
        h("option", { value: "medium" }, "Medium"),
        h("option", { value: "high" }, "High"),
      ],
    );
  },

  checkbox: (params: EditRendererParams) =>
    h("input", {
      type: "checkbox",
      autofocus: true,
      checked: params.initialValue as boolean,
      onChange: (e: Event) => {
        const target = e.target as HTMLInputElement;
        params.onValueChange(target.checked);
        params.onCommit();
      },
      style: { width: "20px", height: "20px" },
    }),
};

const columns: ColumnDefinition[] = [
  { field: "id", cellDataType: "number", width: 60, headerName: "ID" },
  {
    field: "title",
    cellDataType: "text",
    width: 300,
    headerName: "Title",
    editable: true, // Uses default text input
  },
  {
    field: "priority",
    cellDataType: "text",
    width: 120,
    headerName: "Priority",
    editable: true,
    editRenderer: "prioritySelect", // Custom editor
  },
  {
    field: "completed",
    cellDataType: "boolean",
    width: 100,
    headerName: "Done",
    editable: true,
    editRenderer: "checkbox", // Custom editor
  },
];

const tasks: Task[] = [
  { id: 1, title: "Write documentation", priority: "high", completed: false },
  { id: 2, title: "Fix bugs", priority: "medium", completed: true },
  { id: 3, title: "Add tests", priority: "low", completed: false },
];

const dataSource = createClientDataSource(tasks);
</script>

<template>
  <div style="width: 600px; height: 300px">
    <GpGrid
      :columns="columns"
      :data-source="dataSource"
      :row-height="40"
      :edit-renderers="editRenderers"
    />
  </div>
</template>

Dark Mode

<template>
  <GpGrid
    :columns="columns"
    :row-data="data"
    :row-height="36"
    :dark-mode="true"
  />
</template>

API Reference

GpGridProps

ColumnDefinition

Renderer Types

import type { VNode } from "vue";

// Cell renderer receives these params
interface CellRendererParams {
  value: CellValue; // Current cell value
  rowData: Row; // Full row data
  column: ColumnDefinition; // Column definition
  rowIndex: number; // Row index
  colIndex: number; // Column index
  isActive: boolean; // Is this the active cell?
  isSelected: boolean; // Is this cell in selection?
  isEditing: boolean; // Is this cell being edited?
}

// Vue cell renderer - can return VNode or string
type VueCellRenderer = (params: CellRendererParams) => VNode | string | null;

// Edit renderer receives additional callbacks
interface EditRendererParams extends CellRendererParams {
  initialValue: CellValue;
  onValueChange: (newValue: CellValue) => void;
  onCommit: () => void;
  onCancel: () => void;
}

// Vue edit renderer - returns VNode for edit input
type VueEditRenderer = (params: EditRendererParams) => VNode | null;

// Header renderer params
interface HeaderRendererParams {
  column: ColumnDefinition;
  colIndex: number;
  sortDirection?: "asc" | "desc";
  sortIndex?: number; // For multi-column sort
  onSort: (direction: "asc" | "desc" | null, addToExisting: boolean) => void;
}

// Vue header renderer
type VueHeaderRenderer = (
  params: HeaderRendererParams,
) => VNode | string | null;

Keyboard Shortcuts

Styling

The grid injects its own styles automatically. The main container uses these CSS classes:

• .gp-grid-container - Main container
• .gp-grid-container--dark - Dark mode modifier
• .gp-grid-header - Header row container
• .gp-grid-header-cell - Individual header cell
• .gp-grid-row - Row container
• .gp-grid-cell - Cell container
• .gp-grid-cell--active - Active cell
• .gp-grid-cell--selected - Selected cell
• .gp-grid-cell--editing - Cell in edit mode
• .gp-grid-filter-row - Filter row container
• .gp-grid-filter-input - Filter input field
• .gp-grid-fill-handle - Fill handle element

Donations

Keeping this library requires effort and passion, I'm a full time engineer employed on other project and I'm trying my best to keep this work free! For all the features.

If you think this project helped you achieve your goals, it's hopefully worth a beer! 🍻

Support the project