React CSV Downloader

Common errors

• Failed prop type: The prop `filename` is marked as required in `CsvDownloader`, but its value is `null`.

  cause The 'filename' prop was not provided to the CsvDownloader component, or was explicitly set to null/undefined.
  fix Add a `filename` prop with a string value: `<CsvDownloader filename="my_data_export" ... />`.

• Module not found: Can't resolve 'react-csv-downloader' in '.../src/App.js'

  cause The `react-csv-downloader` package is either not installed or the import path is incorrect.
  fix First, ensure the package is installed by running `npm install --save react-csv-downloader`. Then, verify the import statement is `import CsvDownloader from 'react-csv-downloader';`.

• TypeError: Cannot read properties of undefined (reading 'map') (or similar data processing error in the browser console leading to an empty CSV)

  cause The `datas` prop did not resolve to a correctly formatted array of objects, or the array was empty unexpectedly. This often happens with async data if the promise doesn't resolve or resolves with incorrect data.
  fix Debug the `datas` prop's value. If it's an array, ensure it contains objects. If it's a function, confirm it returns a `Promise` that resolves to an array of objects, and that the resolved data is not empty or malformed.

• React.Children.only expected to receive a single React element child.

  cause The `CsvDownloader` component was given multiple children, or a non-element child (e.g., a string or fragment) when used as a wrapper for a trigger element.
  fix Ensure `CsvDownloader` wraps only a single React element, like a `<button>` or `<a>`. If you don't need to wrap a child, use the `text` prop instead: `<CsvDownloader text="Download" ... />`.

Warnings

• breaking Version 3.0.0 of `react-csv-downloader` included a migration to TypeScript and internal dependency updates. While no explicit API breaks were announced, projects relying on specific internal behaviors or older browser compatibility might experience subtle changes. Thorough testing is recommended when upgrading from v2.x.x.
  Fix: Review component usage and test thoroughly, especially if relying on previous dependency behaviors or browser-specific rendering nuances. Ensure your project's TypeScript configuration is compatible.
• gotcha The `filename` prop is marked as required in the component's type definition and documentation, but examples sometimes omit it. Not providing this prop will result in console warnings and may lead to unexpected default filenames or behavior in different browser environments.
  Fix: Always explicitly include a `filename` prop with a string value for the `CsvDownloader` component, e.g., `<CsvDownloader filename="my_report" ... />`.
• gotcha Ensure your project's `react` version falls within the peer dependency range (`^16.6.3 || ^17.0.0 || ^18.0.0 || ^19.0.0`). Mismatched peer dependencies can lead to installation warnings, unexpected runtime errors, or instability within your React application.
  Fix: Adjust your project's `react` version or use `package.json` `overrides` or `resolutions` (depending on your package manager) to align with the specified peer dependency range.
• gotcha When providing the `datas` prop as a function, it must return a `Promise` that resolves to an array of plain JavaScript objects. Incorrectly formatted data (e.g., non-Promise return, malformed array, or non-object items) can result in an empty or corrupt CSV file without explicit error messages from the component.
  Fix: Verify that your async `datas` function correctly returns `Promise.resolve(arrayOfObjects)` and that each object in the array represents a row with key-value pairs corresponding to your desired CSV columns.

Install

• npm install react-csv-downloader npm
• yarn add react-csv-downloader yarn
• pnpm add react-csv-downloader pnpm

Imports

• CsvDownloader
  wrong:

  const CsvDownloader = require('react-csv-downloader');

  correct:

  import CsvDownloader from 'react-csv-downloader';

  This package uses a default export for the main component. Ensure your bundler handles ESM imports correctly in modern React setups.
• CsvDownloaderProps

  import type { CsvDownloaderProps } from 'react-csv-downloader';

  For explicit TypeScript prop typing and improved developer experience.
• Column

  type Column = { id: string; displayName: string; };

  While not directly exported, this type signature reflects the expected structure for the 'columns' prop. Define it in your application for better type safety.

Quickstart

Demonstrates how to use `CsvDownloader` with asynchronous data fetching, custom columns, filename options, and both child component and `text` prop usage.

import React, { useState } from 'react';
import CsvDownloader from 'react-csv-downloader';

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

const columns = [
  { id: 'id', displayName: 'User ID' },
  { id: 'name', displayName: 'Full Name' },
  { id: 'email', displayName: 'Email Address' },
];

const MyCsvExporter: React.FC = () => {
  const [loading, setLoading] = useState(false);

  // Simulate an async data fetch
  const getAsyncData = (): Promise<DataRow[]> => {
    setLoading(true);
    return new Promise((resolve) => {
      setTimeout(() => {
        const data: DataRow[] = [
          { id: 1, name: 'John Doe', email: 'john.doe@example.com' },
          { id: 2, name: 'Jane Smith', email: 'jane.smith@example.com' },
          { id: 3, name: 'Peter Jones', email: 'peter.jones@example.com' },
        ];
        setLoading(false);
        resolve(data);
      }, 1500);
    });
  };

  return (
    <div>
      <h1>User Data Export</h1>
      <p>Click the button to download user data as a CSV file.</p>
      <CsvDownloader
        columns={columns}
        datas={getAsyncData} // Using async function resolver
        filename="user_data_export"
        extension=".csv"
        separator=";"
        prefix={true} // Add timestamp prefix
      >
        <button disabled={loading}>
          {loading ? 'Preparing...' : 'Download CSV'}
        </button>
      </CsvDownloader>
      <br />
      <p>Or a simpler button without children:</p>
      <CsvDownloader
        datas={[{ name: 'Alice', age: 30 }, { name: 'Bob', age: 24 }]}
        filename="simple_data"
        text="Download Simple CSV"
      />
    </div>
  );
};

export default MyCsvExporter;