@poserjs/react-table-csv

ReactTableCSV

ReactTableCSV is a lightweight React component for exploring tabular data with a rich, spreadsheet‑like UI. It parses CSV (via PapaParse), renders a flexible table, and supports filtering, multi‑column sorting, grouping with reducers, pinning, splitting, per‑column styling, row numbers, and persistent settings (export/import/localStorage). It also ships with an optional dashboard wrapper powered by duckdb-wasm to query one or more datasets (or attached DuckDB database files) and render multiple views.

Key Features

• CSV parsing with PapaParse (header: true, numeric typing, BOM/Excel‑friendly export).
• Filters: substring and operator filters (>, <, >=, <=, =, <>) with per‑column type (auto/text/number).
• Sorting: multi‑column (text/number) via Settings or header toggles.
• Grouping: group by selected columns, reduce others via reducers:
  • Counts: cnt (non-empty only), rowcnt (all rows), unique cnt (non-empty unique), unique rowcnt (all unique)
  • Aggregates: sum, avg, min, max, min - max, concat, unique concat, first, last.
• Column pinning (sticky), drag re‑ordering, hide/show, width, alignment, text/background color, bold, nowrap.
• Column resizing with a drag handle on headers when Customize mode is on. Widths persist in settings.
• Split tables by selected columns (one table per unique combination) with filters rendered on the first split table.
• Row numbers (resets per table) and stable internal row IDs for React keys.
• Settings: export/import JSON (with clipboard copy and a modal to copy manually), autosave to localStorage, Copy URL with embedded defaultSetting query param.
• Themes: lite, dark, solarized, dracula, monokai, and gruvbox (local CSS Modules; no Tailwind dependency).
• Optional dashboard mode with multiple datasets and SQL views via duckdb-wasm (and support for attaching external DuckDB database files).
• Safer layout defaults: a minimum component width is enforced; Max‑width accepts px, %, and vh units.
• Dashboard layout packs multiple tables per row when limited widths are provided, or uses full width for unlimited.

Using the Component in Your App

Usage (Next.js App Router example)

"use client";
import React from "react";
import { ReactTableCSV } from "@poserjs/react-table-csv";

const csv = `Name,Department,Salary\nAlice,Engineering,120000\nBob,Sales,90000`;

export default function Page() {
  return (
    <main>
      <ReactTableCSV
        csvString={csv}
        downloadFilename="data.csv"
        storageKey="react-table-csv-key"
        defaultSettings={{ theme: "lite", showFilterRow: true }}
      />
    </main>
  );
}

// Load from a remote file
// <ReactTableCSV csvURL="/path/to/data.csv" />

// Or pass pre-parsed PapaParse output
// const parsed = Papa.parse(csvText, { header: true });
// <ReactTableCSV csvData={parsed} />

Dashboard Mode (duckdb-wasm or none)

Use ReactDashboardCSV to register one or more CSV datasets and define views that render as tables. Dataset keys become DuckDB table names. Whole DuckDB database files can also be attached via the dbs prop and referenced in SQL using the provided keys as database names.

Set db to 'duckdb' (default) to enable SQL queries via duckdb-wasm, or 'none' to render datasets directly without DuckDB.

Peer dependency: @duckdb/duckdb-wasm (installed by the app). The component handles multiple versions of the API.

import { ReactDashboardCSV } from "@poserjs/react-table-csv";

export default function Page() {
  return (
    <ReactDashboardCSV
      db="duckdb" // or 'none'
      layout={[2, 1]} // optional: number of tables per row
      dbs={{
        stats: { dbURL: "/stats.duckdb" },
      }}
      datasets={{
        capitals: { title: "US State Capitals", csvURL: "/us-state-capitals.csv", format: { type: 'csv', header: true } },
        cities:   { title: "US Cities (multi‑year)", csvURL: "/us-cities-top-1k-multi-year.csv", format: { type: 'csv', header: true } },
        // Or: raw CSV string
        // inlineData: { csvString: "col1,col2\nA,1\nB,2" },
        // Or: pre-parsed data (Papa.parse result or { headers, data })
        // preParsed: { csvData: { headers: ["A","B"], data: [{ A: 1, B: 2 }] } },
      }}
      views={{
        byInitial: {
          title: "States by Initial",
          sql: `SELECT substr(t.state,1,1) AS Initial, t.state AS StateName, t.capital AS CapitalCity FROM capitals AS t ORDER BY 1, 2`,
          props: { downloadFilename: "capitals-by-initial.csv", defaultSettings: { tableMaxWidth: "480px" } },
        },
        topCities2014: {
          title: "Top US Cities by Population (2014)",
          sql: `SELECT State, City, year AS Year, Population FROM cities WHERE year = 2014 ORDER BY Population DESC LIMIT 15`,
          props: { /* any ReactTableCSV props */ },
        },
      }}
    />
  );
}

Notes

• Datasets: exactly one of csvURL, csvString, or csvData should be provided per dataset.
• Dataset keys are used as DuckDB table names in SQL; quote if using special characters, e.g. SELECT * FROM "my-table".
• The dashboard normalizes DuckDB proxy rows using toJSON() internally and serializes Date values to ISO strings for stable display/export.

ReactTableCSV Props

• csvString?: string CSV text to render.
• csvURL?: string URL to fetch CSV data from. Non-OK responses surface an error with the HTTP status and message.
• csvData?: object Result of Papa.parse ({ data, meta: { fields } }) to use directly. One of csvString, csvURL, or csvData must be provided.
• downloadFilename?: string Filename for exports. Default "data.csv".
• storageKey?: string localStorage key for settings. Default "react-table-csv-key".
• defaultSettings?: string | object Either a JSON string or a plain object with the same schema as exported settings. Used as defaults and as fallback if localStorage is missing/corrupt.
• title?: string Optional title displayed in a themed header above the table.
• collapsed?: boolean Render the table initially collapsed with a toggle in the header.
• maxHeight?: string Limit table height (e.g., '400px', '50vh'). Use 'unlimited' for no limit.
• maxWidth?: string Limit table width (e.g., '400px', '80%'). Use 'unlimited' for no limit.
• fontSize?: number Font size for table values in pixels. Default 13.
• Theme selection is managed inside the component's settings. Use the Settings panel to cycle themes; the current theme is saved to localStorage and included when exporting settings.

ReactDashboardCSV Props

• datasets?: Record<string, { title?: string; csvURL?: string; csvString?: string; csvData?: any; format?: { type?: 'csv' | 'json'; header?: boolean; separator?: string; escape?: string; columns?: string[] } }>
  • One of csvURL, csvString, or csvData must be set for each dataset.
  • format defaults to CSV with header: true, separator: ',', and escape: '"'. When header is false, provide columns names.
• dbs?: Record<string, { title?: string; dbURL: string }>
  • Attach external DuckDB database files by URL. The key becomes the database name for queries, e.g. stats.my_table.
• views?: Record<string, { title?: string; sql?: string; dataset?: string; props?: ReactTableCSVProps }>
  • With db="duckdb" (default): each view runs its sql against the registered datasets and renders a table. If sql is omitted, the view shows SELECT * from the specified dataset, or from the only dataset if exactly one is provided.
  • With db="none": DuckDB is not loaded. Each view must reference a dataset (or the only dataset is used) and the component passes that dataset directly to ReactTableCSV (via csvURL, csvString, or csvData). In this mode, omit sql.
  • Optional title shows above the table; optional collapsed renders the view initially collapsed with a toggle.
• layout?: number[] Optional array indicating how many views to place per row, e.g., [2, 1, 3]. Extra views beyond the array are rendered one per row.

Exported/Imported Settings (high‑level)

• { version, theme, columnStyles, columnOrder, hiddenColumns, filters, dropdownFilters, filterMode, showFilterRow, pinnedAnchor, showRowNumbers, customize, tableMaxHeight, tableMaxWidth, fontSize }

Notes about settings

• Settings export attempts to copy to clipboard and also opens a modal with the JSON so the value can be read or copied manually.
• Settings used in defaultSettings can be provided as a string or as a plain object.
• Entering Customize mode automatically shows the Settings panel.

Resetting Settings

Call resetSettings() to revert the table to its initial configuration. The reset also turns off customize mode (or respects a customize value from provided defaults) and returns the applied settings object.

Development

See the CONTRIBUTING.md file for details.

License

Licensed under the MIT License. See the LICENSE file for details.