react-csvify

React CSVify

A production-ready, composable, and fully typed React component for generating and downloading CSV, TSV, and JSON files from any dataset. Designed for advanced customization, zero dependencies, and seamless integration into modern React or Next.js applications.

📚 Documentation

• 📖 API Reference - Complete prop reference and function documentation
• 💡 Examples & Use Cases - Real-world examples and advanced patterns
• 🛠️ Guide - Step-by-step implementation guides
• 🤖 Schema Reference - JSON schema definitions for AI/automation
• ❓ FAQ - Frequently asked questions

🚀 Key Features

• 🎯 Zero Configuration - Works out of the box with sensible defaults
• 📊 Multiple Format Support - Export to CSV, TSV, and JSON with unified API
• 🔄 Bidirectional CSV - Parse CSV strings back into typed objects
• ✨ Advanced Data Transformation - Custom formatters and value transformers
• 🚀 Progress Tracking - Monitor download progress for large datasets
• 🎨 Fully Customizable UI - Use default link or inject your own button
• 📦 Zero Dependencies - React-only, works everywhere
• ♿ Accessible - Screen reader friendly and keyboard accessible
• 🌳 Tree-Shakable - Import only what you need
• ⚡ High Performance - Optimized for large datasets
• 🧪 Fully Tested - Comprehensive test suite with >80% coverage
• 📝 TypeScript Ready - 100% type-safe API

📦 Installation

npm install react-csvify@latest
# or
yarn add react-csvify@latest
# or
pnpm add react-csvify@latest

Bundle Size Impact

• Minified: ~12KB
• Minified + Gzipped: ~4KB
• Zero runtime dependencies
• Tree-shakable exports

✅ Prerequisites

Requirement	Version	Notes
React	16+	Hooks-based components
React DOM	16+	Standard DOM rendering
TypeScript	4.5+	Recommended for best experience
Node.js	16+	For development and building

Note: This package has react and react-dom as peer dependencies. Ensure they're already installed in your project.

🚀 Quick Start

Basic Usage

"use client";
import React from "react";
import { DownloadButton } from "react-csvify";

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

export default function BasicExample() {
  const users: User[] = [
    { id: 1, name: "Alice Johnson", email: "[e-mail]" },
    { id: 2, name: "Bob Smith", email: "[e-mail]" },
    { id: 3, name: "Carol Davis", email: "[e-mail]" },
  ];

  return (
    <DownloadButton
      data={users}
      filename="users.csv"
    />
  );
}

Multiple Format Support

import { DownloadButton } from "react-csvify";

export default function MultiFormatExample() {
  const data = [
    { id: 1, name: "Alice", active: true },
    { id: 2, name: "Bob", active: false },
  ];

  return (
    <div className="space-y-4">
      {/* Export as CSV */}
      <DownloadButton data={data} filename="data.csv" />

      {/* Export as TSV */}
      <DownloadButton data={data} filename="data.tsv" />

      {/* Export as JSON */}
      <DownloadButton data={data} filename="data.json" />
    </div>
  );
}

Advanced Usage with Validation & Transformation

"use client";
import React, { useState } from "react";
import {
  DownloadButton,
  validateCsvData,
  formatCsvValue,
  parseCSV,
} from "react-csvify";

export default function AdvancedExample() {
  const [validationErrors, setValidationErrors] = useState<string[]>([]);
  const data = [
    { id: 1, name: "Alice", joinDate: "2024-01-15", score: 95.5 },
    { id: 2, name: "Bob", joinDate: "2024-02-20", score: 88.3 },
  ];

  const handleDownload = () => {
    // Validate before download
    const validation = validateCsvData(data, {
      maxRows: 10000,
      maxFieldSize: 5000,
      allowEmpty: false,
    });

    if (!validation.valid) {
      setValidationErrors(validation.errors);
      return;
    }

    setValidationErrors([]);
  };

  return (
    <div>
      {validationErrors.length > 0 && (
        <div className="error-box">
          {validationErrors.map((err, idx) => (
            <p key={idx}>{err}</p>
          ))}
        </div>
      )}

      <DownloadButton
        data={data}
        filename="users.csv"
        transformValue={(value, key) => {
          if (key === "score" && typeof value === "number") {
            return value.toFixed(1);
          }
          return String(value);
        }}
        onDownloadStart={handleDownload}
        customButton={
          <button className="bg-blue-500 text-white px-4 py-2 rounded">
            Export CSV
          </button>
        }
      />
    </div>
  );
}

Core Features

Component: DownloadButton

The main React component for triggering downloads.

<DownloadButton
  data={users}
  filename="export.csv"
  customHeaders={["ID", "Full Name", "Email"]}
  transformValue={(value, key, row) => {
    // Custom formatting
    if (key === "joinDate") {
      return new Date(value as string).toLocaleDateString();
    }
    return String(value);
  }}
  onDownloadStart={() => console.log("Starting...")}
  onProgress={(progress) => console.log(`${progress.percentage}% complete`)}
  onDownloadComplete={() => console.log("Done!")}
  onError={(error) => console.error(error)}
/>

Utilities: Parse & Validate

Parse CSV strings back to objects:

import { parseCSV, parseTSV, detectDelimiter } from "react-csvify";

const csvContent = `id,name,email
1,Alice,[e-mail]
2,Bob,[e-mail]`;

const result = parseCSV(csvContent);
if (result.success) {
  console.log(result.data); // Typed array of objects
}

// Auto-detect delimiter
const delimiter = detectDelimiter(csvContent);

Validate data before export:

import { validateCsvData, detectDataIssues } from "react-csvify";

const validation = validateCsvData(data, {
  maxRows: 10000,
  allowEmpty: false,
});

if (!validation.valid) {
  console.error("Validation errors:", validation.errors);
}

// Detect potential issues
const issues = detectDataIssues(data);

Format & transform values:

import { formatCsvValue, formatCsvRow } from "react-csvify";

const formatted = formatCsvValue("Hello, World", true);
console.log(formatted.formatted); // "Hello, World"

const row = formatCsvRow(
  ["id", "name", "active"],
  ",",
  true
);

Generate Content Programmatically

import {
  generateContent,
  generateContentWithProgress,
} from "react-csvify";

// Simple generation
const csv = generateContent(data, "csv", {
  delimiter: ",",
  quoteValues: true,
  customHeaders: ["ID", "Name"],
});

// With progress tracking
generateContentWithProgress(
  largeDataset,
  "json",
  (progress) => {
    console.log(`Processing: ${progress.percentage}%`);
  },
  { prettifyJson: true }
);

Advanced Examples

See EXAMPLES.md for:

• Filtering and sorting before export
• Batch processing multiple exports
• React Query integration
• Form data export
• Database export workflows
• Conditional column selection
• Custom styling and theming

Prop Reference

Prop	Type	Default	Description
data	T[]	Required	Array of objects to export
filename	string	Required	Output filename (extension determines format)
delimiter	string	","	Field delimiter (CSV only)
quoteValues	boolean	true	Wrap values in quotes
transformValue	(value, key, row) => string	–	Custom value formatter
customHeaders	string[]	–	Override auto-generated headers
customButton	ReactNode	–	Custom trigger button/component
emptyDataMessage	string	"No data available."	Message when data is empty
onDownloadStart	() => void	–	Called before generation
onDownloadComplete	() => void	–	Called after successful download
onError	(error: Error) => void	–	Error handler
onProgress	(progress) => void	–	Progress callback for large datasets
chunkSize	number	1000	Rows processed before progress update

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

Changelog

See CHANGELOG.md for version history and updates.

Versioning

We use Semantic Versioning. Current version: 1.1.0

License

This project is licensed under the ISC License - see the LICENSE file for details.

Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: Report security issues privately to maintainers

⭐ Support the Project

If you find this library helpful:

• ⭐ Star the repository - Helps others discover the project
• 🐛 Report bugs - Help improve stability
• 💡 Request features - Suggest improvements
• 📖 Improve docs - Help other developers
• 🤝 Contribute code - Join development

Your support keeps this project maintained and improved! 🚀

Acknowledgments

• Built with React and TypeScript
• Inspired by common data export patterns
• Thanks to all contributors and users

Made with ❤️ by ninsau