Overview :
NOTE: This is a fork of https://github.com/abdennour/react-csv meant to fix add \r\n line breaks, so that line breaks are respected in Windows Notepad.
Generate a CSV file from given data.
This data can be an array of arrays, an array of literal objects, or strings.
Example :
; const csvData = "firstname" "lastname" "email" "Ahmed" "Tomi" "ah@smthing.co.com" "Raed" "Labes" "rl@smthing.co.com" "Yezzi" "Min l3b" "ymin@cocococo.com";<CSVLink data=csvData>Download me</CSVLink>;// or<CSVDownload data=csvData target="_blank" />;
For more examples, see here 👈🏼
Install
npm install react-csv --save;
Or for non-node developers, you can use CDN directly:
Components:
This package includes two components: CSVLink
and CSVDownload
.
0. Common Props:
The two components accept the following Props
:
- data Props:
A required property that represents the CSV data. This data can be array of arrays, array of literal objects or string.
Example of Array of arrays
// Array of arrays. Each item is rendered as a CSV linedata = "firstname" "lastname" "email" "Ahmed" "Tomi" "ah@smthing.co.com" "Raed" "Labes" "rl@smthing.co.com" "Yezzi" "Min l3b" "ymin@cocococo.com";
Example of array of literal objects
// Array of literal objects. Each item is rendered as CSV line however the order of fields will be defined by the headers props. If the headers props are not defined, the component will generate headers from each data item.data = firstname: "Ahmed" lastname: "Tomi" email: "ah@smthing.co.com" firstname: "Raed" lastname: "Labes" email: "rl@smthing.co.com" firstname: "Yezzi" lastname: "Min l3b" email: "ymin@cocococo.com" ;
Example of strings
// A string can be used if the data is already formatted correctly data = `firstname,lastnameAhmed,TomiRaed,LabesYezzi,Min l3b`; // or using 3rd party package;data = ;
- headers Props:
Specifying headers
helps to define an order of the CSV fields. The csv content will be generated accordingly.
Notes :
- The meaning of headers with data of type
Array
is to order fields AND prepend those headers at the top of the CSV content.- The meaning of headers with data of type
String
data is only prepending those headers as the first line of the CSV content.
Custom Header Labels
Custom header labels can be used when converting data of type Object
to CSV by having the header array itself be an array of literal objects of the form:
label: /* Label to display at the top of the CSV */ key: /* Key to the data */
If the header array is an array of strings, the header labels will be the same as the keys used to index the data objects.
Example:
; headers = label: "First Name" key: "firstname" label: "Last Name" key: "lastname" label: "Email" key: "email" ; data = firstname: "Ahmed" lastname: "Tomi" email: "ah@smthing.co.com" firstname: "Raed" lastname: "Labes" email: "rl@smthing.co.com" firstname: "Yezzi" lastname: "Min l3b" email: "ymin@cocococo.com" ; <CSVLink data=data headers=headers> Download me</CSVLink>;
Nested JSON data
It is possible to reference nested strings in your data using dot notation
headers = label: 'First Name' key: 'details.firstName' label: 'Last Name' key: 'details.lastName' label: 'Job' key: 'job' ; data = details: firstName: 'Ahmed' lastName: 'Tomi' job: 'manager' details: firstName: 'John' lastName: 'Jones' job: 'developer';
- separator Props:
Following a request to add this feature , from 1.0.1
release, react-csv
supports separator
props which is equals by default a comma ,
.
; <CSVLink data=array separator=";"> Download me</CSVLink>;/* This will generate CSV with ";" as delimiter (separator) */
1. CSVLink Component:
It renders a hyperlink and clicking on it will trigger the download action of the CSV document.
It does not accept only data
and headers
props, but it also renders all props of HTMLAnchor
tag. (className, target,....)
- filename Props:
filename
is another props restricted to CSVLink
. It specifies the filename of the downloaded CSV.
example
; <CSVLink data=data filename="my-file.csv" className="btn btn-primary" target="_blank"> Download me</CSVLink>;
- onClick Props:
onClick
is another props restricted to CSVLink
.
If it is defined, it means 3 things:
1 - It will run at the top of the click handling logic.
2 - [Sync] If it returns an explicit false
, the return will be interpreted as a claim to stop the click handling, then, the next logic will not be executed if so.
3 - [Async] If it is async, "done" argument must be called if you want to invoke the handling of the component. (check examples below)
4 - [Async] If it is async (includes api call, timeout,... ) and it calls done with false
will be interpreted as a claim to stop the click handling, then, the next logic will not be executed if so.
examples
- 🔬 Sync + Proceed
; <CSVLink data=data onClick= { console; // 👍🏻 Your click handling logic }> Download me</CSVLink>;
- 🔬 Sync + Don't Proceed
; <CSVLink data=data onClick= { console; return false; // 👍🏻 You are stopping the handling of component }> Download me</CSVLink>;
- 🔬 Async + Proceed
; <CSVLink data=data asyncOnClick=true onClick= { axios; }> Download me</CSVLink>;
- 🔬 Async + Don't Proceed
; <CSVLink data=data asyncOnClick=true onClick= { axios; }> Download me</CSVLink>;
2. CSVDownload Component:
It triggers downloading ONLY on mounting the component. so , be careful to render this component whenever it is needed.
It does not accept only data
and headers
props , but also , it takes advantage of all arguments of window.open
function known that its signature is :
window;
Thus, target
, specs
and replace
Props are available .
example
; <CSVDownload data=data target="_blank" />;
For non-node developers, they have to use CDN version :
Contribution :
-
Unit-tests must cover at least 90% of code .
-
Write documentation of the new class, function, method, attribute ..so on.. following JSDoc syntax.
-
Add an example for the new feature to
sample-site
. -
npm start
runs thesample-site
-
npm run docgen
generates documentation in HTML output. -
npm run cdn
generate a bundle to be used as CDN
Donation
If this project help you reduce time to develop, you can give me a cup of coffee 🍵 :)