@aspect/nup-xlsx-preview

Ultra-light Excel visualization component with virtual scrolling for 100K+ rows.

Features

• Ultra Light: < 80KB gzipped (vs 800KB+ competitors)
• Virtual Scroll: Smooth scrolling for 100K+ rows
• CSS Grid Renderer: No heavy Canvas, pure HTML/CSS
• Perfect Merge Cells: Full support for merged cell regions
• 7 Themes: 4 light, 2 dark, 1 accessible (WCAG AA)
• Keyboard Navigation: Full ARIA support
• Print Ready: Optimized CSS for printing
• Framework Adapters: React 18, Vue 3, Vanilla JS
• Edge Compatible: Works in Cloudflare Workers

Installation

npm install @aspect/nup-xlsx-preview

Quick Start

React

import { ReactSpreadsheetPreview } from '@aspect/nup-xlsx-preview/react';
import '@aspect/nup-xlsx-preview/styles';

function App() {
  return (
    <ReactSpreadsheetPreview
      workbook={workbook}
      theme="modern"
      height="600px"
      onCellClick={(e) => console.log(e.cellRef)}
    />
  );
}

Vue 3

<script setup>
import { NupSpreadsheetPreview } from '@aspect/nup-xlsx-preview/vue';
import '@aspect/nup-xlsx-preview/styles';
</script>

<template>
  <NupSpreadsheetPreview
    :workbook="workbook"
    theme="modern"
    height="600px"
    @cell-click="handleCellClick"
  />
</template>

Vanilla JS

import { createSpreadsheetPreview } from '@aspect/nup-xlsx-preview/vanilla';
import '@aspect/nup-xlsx-preview/styles';

const preview = createSpreadsheetPreview('#container', {
  workbook: workbook,
  theme: 'modern',
  height: '600px',
  onCellClick: (e) => console.log(e.cellRef),
});

// API
preview.scrollToCell('Z100');
preview.search('total');

Configuration

| Prop | Type | Default | Description | |------|------|---------|-------------| | workbook | NupWorkbook | required | Workbook data | | activeSheet | number | 0 | Active sheet index | | theme | ThemeName \| NupThemeConfig | 'default' | Theme name or custom config | | width | string \| number | '100%' | Container width | | height | string \| number | '400px' | Container height | | showHeaders | boolean | true | Show row/column headers | | showGridLines | boolean | true | Show cell grid lines | | showSheetTabs | boolean | true | Show sheet tabs | | selectable | boolean | true | Enable cell selection | | resizable | boolean | true | Enable column resize | | searchable | boolean | false | Show search bar | | copyable | boolean | true | Enable Ctrl+C copy | | keyboardNavigation | boolean | true | Enable arrow key navigation | | frozenRows | number | 0 | Frozen rows count | | frozenCols | number | 0 | Frozen columns count | | overscan | number | 5 | Extra rows/cols to render |

Events

| Event | Payload | Description | |-------|---------|-------------| | onCellClick | CellClickEvent | Cell clicked | | onCellDoubleClick | CellClickEvent | Cell double-clicked | | onCellRightClick | CellClickEvent | Cell right-clicked | | onSelectionChange | SelectionRange \| null | Selection changed | | onSheetChange | number | Active sheet changed | | onColumnResize | { colIndex, width } | Column resized | | onScroll | ScrollPosition | Scroll position changed | | onSearch | SearchResult[] | Search results updated | | onCopy | ClipboardData | Cells copied |

Instance Methods

// Navigation
preview.scrollTo(row, col);
preview.scrollToCell('A100');

// Selection
preview.selectCell('B5');
preview.selectAll();
preview.clearSelection();
const selection = preview.getSelection();

// Sheets
preview.setActiveSheet(1);

// Search
const results = preview.search('revenue');
preview.highlightResults(results);
preview.clearHighlights();

// Copy
await preview.copySelection();

// Resize
preview.setColumnWidth(0, 150);
preview.autoFitColumn(0);

// Lifecycle
preview.refresh();
preview.destroy();

Themes

Built-in themes:

• default - Google Sheets inspired
• excel - Microsoft Excel classic
• modern - Clean modern design
• minimal - Ultra minimal
• dark - Dark mode
• midnight - GitHub dark
• accessible - WCAG AAA compliant

Custom Theme

const customTheme: NupThemeConfig = {
  name: 'custom',
  colors: {
    background: '#ffffff',
    foreground: '#1a1a1a',
    grid: '#e0e0e0',
    headerBackground: '#f5f5f5',
    headerForeground: '#666666',
    selectionBorder: '#0066cc',
    selectionBackground: 'rgba(0, 102, 204, 0.1)',
    frozenBorder: '#cccccc',
  },
  fonts: {
    family: 'Inter, sans-serif',
    size: '13px',
    headerSize: '11px',
  },
};

Accessibility

• Full keyboard navigation (Arrow keys, Tab, Enter, etc.)
• ARIA roles and attributes
• High contrast theme
• Colorblind-friendly variants
• Screen reader support

Print

// Add print styles
import '@aspect/nup-xlsx-preview/styles/print.css';

// Print button
window.print();

Bundle Size

| Package | Size (gzipped) | |---------|---------------| | Core | ~25KB | | React Adapter | ~8KB | | Vue Adapter | ~8KB | | Vanilla Adapter | ~10KB | | Styles | ~4KB | | Total | < 55KB |

Browser Support

• Chrome 90+
• Firefox 90+
• Safari 14+
• Edge 90+

License

Commercial license - $49/month per project

Related Packages

• @aspect/nup-xlsx-core - XLSX parser
• @aspect/nup-xlsx-tokens - Design tokens and themes
• @aspect/nup-xlsx-export - XLSX export
• @aspect/nup-xlsx-editor - Full editor