@smallwebco/tinypivot-vue

@smallwebco/tinypivot-vue

A lightweight data grid with free pivot tables, Pro charts, and optional AI-powered data exploration for Vue 3. Under 50KB gzipped — 10x smaller than AG Grid.

Live Demo · Buy License

Why TinyPivot?

• Lightweight: Under 50KB gzipped vs 500KB+ for AG Grid
• Free Pivot Tables: Sum aggregations, totals, and calculated fields included
• Pro Upgrade: Advanced aggregations, charts, AI Data Analyst, and no watermark
• AI Data Analyst (Pro): Natural language queries with BYOK — use your own OpenAI/Anthropic key
• Lifetime License: No subscriptions — buy once, use forever

Installation

pnpm add @smallwebco/tinypivot-vue

Quick Start

<script setup lang="ts">
import { DataGrid } from '@smallwebco/tinypivot-vue'
import '@smallwebco/tinypivot-vue/style.css'

const data = [
  { id: 1, region: 'North', product: 'Widget A', sales: 12500, units: 150 },
  { id: 2, region: 'North', product: 'Widget B', sales: 8300, units: 95 },
  { id: 3, region: 'South', product: 'Widget A', sales: 15200, units: 180 },
  { id: 4, region: 'South', product: 'Widget B', sales: 9800, units: 110 },
]
</script>

<template>
  <DataGrid
    :data="data"
    :enable-export="true"
    :enable-search="true"
    :enable-pagination="true"
    :page-size="100"
    theme="light"
  />
</template>

Theming

TinyPivot ships 22 themes — 2 neutral (light, dark) plus 10 brand themes each with a light and dark variant. Themes are applied via the theme prop on DataGrid.

Quick start

<DataGrid :data="data" theme="slate-dark" />

theme="auto" resolves to 'light' or 'dark' based on the user's system preference (prefers-color-scheme).

Available themes

Custom themes

Brand themes redefine ~25 CSS custom property tokens at the grid root. You can override these in your own CSS to create a custom theme:

<template>
  <DataGrid :data="data" theme="light" class="my-brand" />
</template>

<style>
.vpg-data-grid.my-brand {
  --vpg-accent: #ff6b35;
  --vpg-accent-hover: #e55426;
  --vpg-surface-bg: #fafaf7;
  --vpg-surface-panel: #f0eee7;
  /* …override any of the tokens below */
}
</style>

Token reference — these are the variables you can override:

• Surfaces: --vpg-surface-bg, --vpg-surface-panel, --vpg-surface-elevated, --vpg-surface-hover, --vpg-surface-selected, --vpg-surface-striped
• Text: --vpg-text-primary, --vpg-text-secondary, --vpg-text-muted, --vpg-text-inverse
• Borders: --vpg-border-default, --vpg-border-strong, --vpg-border-subtle
• Accent: --vpg-accent, --vpg-accent-hover, --vpg-accent-soft-bg, --vpg-accent-soft-text, --vpg-focus-ring
• States: --vpg-state-error, --vpg-state-warning, --vpg-state-success, --vpg-state-info
• Scrollbar: --vpg-scrollbar-thumb, --vpg-scrollbar-track

Custom theme classes layer on top of any preset, so you can start from theme="dark" and tweak just the accent, for example.

Adding a theme switcher

Let users pick their own theme — bind a reactive theme value to a <select>:

<script setup lang="ts">
import { DataGrid } from '@smallwebco/tinypivot-vue'
import '@smallwebco/tinypivot-vue/style.css'
import { ref } from 'vue'

const theme = ref<'light' | 'dark' | 'slate' | 'slate-dark' | 'emerald' | 'emerald-dark'>('dark')
const data = [/* ... */]
</script>

<template>
  <select v-model="theme">
    <option value="light">Light</option>
    <option value="dark">Dark</option>
    <option value="slate-dark">Slate (dark)</option>
    <option value="emerald-dark">Emerald (dark)</option>
    <!-- …add more themes -->
  </select>

  <DataGrid :data="data" :theme="theme" />
</template>

Features

Props

Events

Export

When enableExport is true (the default), the toolbar shows a single Export dropdown button. Clicking it opens a menu with two items:

• CSV — always available (free). Downloads a .csv file of the current view.
• Excel (.xlsx) — Pro only. Free users see this item disabled with a Pro badge. Pro users get a styled .xlsx download. exceljs (~250 KB) loads lazily via dynamic import — never part of your main bundle.

CSV Export (Free)

import { exportToCSV, exportPivotToCSV } from '@smallwebco/tinypivot-vue'

exportToCSV(data, columns, { filename: 'my-data.csv' })

Excel (XLSX) Export (Pro)

import { exportToXLSX, exportPivotToXLSX } from '@smallwebco/tinypivot-vue'

// Flat grid
await exportToXLSX(data, columns, {
  filename: 'report.xlsx',
  sheetName: 'Sales',
  numberFormats: { revenue: '#,##0.00' },
})

// Pivot table
await exportPivotToXLSX(pivotData, rowFields, columnFields, valueFields, {
  filename: 'pivot.xlsx',
})

Pivot XLSX: two-sheet workbook

Pivot XLSX export produces a two-sheet workbook:

1. Pivot — the styled pivot summary (merged column headers, bold totals row, frozen header).
2. Source Data — the underlying source rows as an interactive Excel Table (filter/sort dropdowns, TableStyleMedium2). Open it in Excel and choose Insert → PivotTable to build a native PivotTable in two clicks.

Note: TinyPivot does not generate a native Excel PivotTable object (exceljs does not support writing pivot table XML). The Source Data sheet is the practical alternative.

## Pivot Drill-Down

### Row Group Expand/Collapse (Free)

When a pivot has two or more row fields, each group row displays a `▸`/`▾` chevron. Click to collapse or expand that group. Alt-click collapses/expands every group at the same depth. Collapsed groups still show correct aggregated values over all rows in the group.

By default (`pivot-layout="grouped"`), the parent row value is rendered once as a vertically spanning cell across its children, making the hierarchy immediately readable. Set `:pivot-layout="'tabular'"` to repeat the parent value on every row instead.

```vue
<template>
  <DataGrid
    :data="data"
    @collapse-change="(collapsedPaths) => console.log('Collapsed:', collapsedPaths)"
  />
</template>

Drill-Through to Source Rows (Pro)

Double-click any pivot value cell (including totals) to open a modal with the underlying source rows. Includes a slice description header, paginated table (50/page), and CSV export. Requires a Pro license.

<template>
  <DataGrid
    :data="data"
    @drill-through="({ rows, descriptor }) => console.log(`${descriptor.rowCount} rows`)"
  />
</template>

Disable either behaviour individually:

<DataGrid :data="data" :enable-drill-down="false" :enable-drill-through="false" />

AI Data Analyst (Pro)

Optional AI-powered data analyst that lets users explore data using natural language. Ask questions like "What's the return rate by category?" and get instant results.

See the AI Analyst Demo for a complete working example.

<script setup lang="ts">
import { DataGrid } from '@smallwebco/tinypivot-vue'
import '@smallwebco/tinypivot-vue/style.css'

const data = [/* your data */]

const aiConfig = {
  enabled: true,
  aiEndpoint: '/api/ai-proxy',           // Your AI proxy endpoint
  databaseEndpoint: '/api/tp-database',  // Optional: auto-discover tables
  aiModelName: 'Claude Sonnet 4',        // Optional: display in UI
  persistToLocalStorage: true,           // Preserve conversation on tab switch
}
</script>

<template>
  <DataGrid
    :data="data"
    :ai-analyst="aiConfig"
  />
</template>

AI Analyst Config Options

AI Analyst Events

State Preservation

The AI Analyst preserves state when switching between tabs (Grid, Pivot, Chart, AI):

• Conversation history is maintained in memory
• Query results are preserved
• SQL queries remain accessible via the SQL panel

To persist across page refreshes, enable persistToLocalStorage: true. The conversation will be saved to localStorage using the sessionId as the key.

For production apps, listen to @ai-conversation-update to implement your own persistence:

<template>
  <DataGrid
    :data="data"
    :ai-analyst="aiConfig"
    @ai-conversation-update="saveConversation"
  />
</template>

<script setup>
function saveConversation({ conversation }) {
  // Save to your backend
  api.saveConversation(userId, conversation)
}
</script>

Documentation

See the full documentation for complete API reference, styling, and Pro license activation.

License

• Free Tier: MIT License for core grid and pivot features
• Pro Features: Commercial license required

Purchase at tiny-pivot.com/#pricing

Built with ❤️ by Small Web, LLC