{"id":15029062,"url":"https://github.com/react-csv/react-csv","last_synced_at":"2025-05-14T08:06:21.009Z","repository":{"id":33440034,"uuid":"74758476","full_name":"react-csv/react-csv","owner":"react-csv","description":"React components to build CSV files on the fly basing on Array/literal object of data","archived":false,"fork":false,"pushed_at":"2024-04-03T11:34:59.000Z","size":3822,"stargazers_count":1171,"open_issues_count":134,"forks_count":262,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-05-05T12:46:48.053Z","etag":null,"topics":["csv-document","etl","excel","reactjs","reporting"],"latest_commit_sha":null,"homepage":"http://react-csv.github.io/react-csv/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/react-csv.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["abdennour","mccabemj"],"custom":"https://www.paypal.me/AbdennourT/10"}},"created_at":"2016-11-25T12:55:39.000Z","updated_at":"2025-04-23T10:27:58.000Z","dependencies_parsed_at":"2024-01-17T15:04:41.206Z","dependency_job_id":"d73e0bea-19b5-43f6-9968-48846882653e","html_url":"https://github.com/react-csv/react-csv","commit_stats":{"total_commits":168,"total_committers":40,"mean_commits":4.2,"dds":0.5892857142857143,"last_synced_commit":"d1153c101b95c109b5bcf5a5c2a370a81d522f1e"},"previous_names":["abdennour/react-csv"],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/react-csv%2Freact-csv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/react-csv%2Freact-csv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/react-csv%2Freact-csv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/react-csv%2Freact-csv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/react-csv","download_url":"https://codeload.github.com/react-csv/react-csv/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254101615,"owners_count":22014909,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["csv-document","etl","excel","reactjs","reporting"],"created_at":"2024-09-24T20:09:40.162Z","updated_at":"2025-05-14T08:06:16.001Z","avatar_url":"https://github.com/react-csv.png","language":"JavaScript","readme":"[![Build Status](https://travis-ci.org/abdennour/react-csv.svg?branch=master)](https://travis-ci.org/abdennour/react-csv)\n[![Coverage Status](https://coveralls.io/repos/github/abdennour/react-csv/badge.svg?branch=master)](https://coveralls.io/github/abdennour/react-csv?branch=master)\n\n![](https://raw.githubusercontent.com/rathath/bucket/master/img/react-csv.png)\n\n[![Build Status](https://travis-ci.org/abdennour/react-csv.svg?branch=master)](https://travis-ci.org/abdennour/react-csv)\n[![Coverage Status](https://coveralls.io/repos/github/abdennour/react-csv/badge.svg?branch=master)](https://coveralls.io/github/abdennour/react-csv?branch=master)\n\n# Overview :\n\nGenerate a CSV file from given data.\n\nThis data can be an array of arrays, an array of literal objects, or strings.\n\n# Example :\n\n```js\nimport { CSVLink, CSVDownload } from \"react-csv\";\n\nconst csvData = [\n  [\"firstname\", \"lastname\", \"email\"],\n  [\"Ahmed\", \"Tomi\", \"ah@smthing.co.com\"],\n  [\"Raed\", \"Labes\", \"rl@smthing.co.com\"],\n  [\"Yezzi\", \"Min l3b\", \"ymin@cocococo.com\"]\n];\n\u003cCSVLink data={csvData}\u003eDownload me\u003c/CSVLink\u003e;\n// or\n\u003cCSVDownload data={csvData} target=\"_blank\" /\u003e;\n```\n\nFor more examples, see [here 👈🏼](http://react-csv.github.io/react-csv/)\n\n# Install\n\n```\nnpm install react-csv --save;\n```\n\nOr for non-node developers, you can use CDN directly:\n\n```html\n\u003cscript src=\"https://cdn.rawgit.com/abdennour/react-csv/6424b500/cdn/react-csv-latest.min.js\" type=\"text/javascript\"\u003e\u003c/script\u003e\n```\n\n# Components:\n\nThis package includes two components: `CSVLink` and `CSVDownload`.\n\n## 0. Common Props:\n\nThe two components accept the following `Props`:\n\n### - **data** Props:\n\nA required property that represents the CSV data.\nThis data can be _array of arrays_, _array of literal objects_ or _string_.\nThis can also be a function that returns any of these things.\n\n**Example of Array of arrays**\n\n```js\n// Array of arrays. Each item is rendered as a CSV line\ndata = [\n  [\"firstname\", \"lastname\", \"email\"],\n  [\"Ahmed\", \"Tomi\", \"ah@smthing.co.com\"],\n  [\"Raed\", \"Labes\", \"rl@smthing.co.com\"],\n  [\"Yezzi\", \"Min l3b\", \"ymin@cocococo.com\"]\n];\n```\n\n**Example of array of literal objects**\n\n```js\n// 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.\ndata = [\n  { firstname: \"Ahmed\", lastname: \"Tomi\", email: \"ah@smthing.co.com\" },\n  { firstname: \"Raed\", lastname: \"Labes\", email: \"rl@smthing.co.com\" },\n  { firstname: \"Yezzi\", lastname: \"Min l3b\", email: \"ymin@cocococo.com\" }\n];\n```\n\n**Example of strings**\n\n```js\n// A string can be used if the data is already formatted correctly\n\ndata = `firstname,lastname\nAhmed,Tomi\nRaed,Labes\nYezzi,Min l3b\n`;\n\n// or using 3rd party package\nimport json2csv from \"json2csv\";\ndata = json2csv(arrayOfLiteralObjects);\n```\n\n**Example of function returning data**\n\n```js\n// this function just returns a basic array, but you could also map or return some recently downloaded data in state\nfunction dataFromAsyncProcess() {\n  return [\n    { firstname: \"Ahmed\", lastname: \"Tomi\", email: \"ah@smthing.co.com\" },\n    { firstname: \"Raed\", lastname: \"Labes\", email: \"rl@smthing.co.com\" },\n    { firstname: \"Yezzi\", lastname: \"Min l3b\", email: \"ymin@cocococo.com\" }\n  ];\n}\n```\n\n### - **headers** Props:\n\nSpecifying `headers` helps to define an order of the CSV fields. The csv content will be generated accordingly.\n\n\u003e Notes :\n\u003e\n\u003e - The meaning of headers with data of type `Array` is to order fields AND prepend those headers at the top of the CSV content.\n\u003e - The meaning of headers with data of type `String` data is only prepending those headers as the first line of the CSV content.\n\n##### Custom Header Labels\n\nCustom 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:\n\n```js\n{ label: /* Label to display at the top of the CSV */, key: /* Key to the data */ }\n```\n\nIf the header array is an array of strings, the header labels will be the same as the keys used to index the data objects.\n\nExample:\n\n```js\nimport { CSVLink } from \"react-csv\";\n\nheaders = [\n  { label: \"First Name\", key: \"firstname\" },\n  { label: \"Last Name\", key: \"lastname\" },\n  { label: \"Email\", key: \"email\" }\n];\n\ndata = [\n  { firstname: \"Ahmed\", lastname: \"Tomi\", email: \"ah@smthing.co.com\" },\n  { firstname: \"Raed\", lastname: \"Labes\", email: \"rl@smthing.co.com\" },\n  { firstname: \"Yezzi\", lastname: \"Min l3b\", email: \"ymin@cocococo.com\" }\n];\n\n\u003cCSVLink data={data} headers={headers}\u003e\n  Download me\n\u003c/CSVLink\u003e;\n```\n\n##### Nested JSON data\n\nIt is possible to reference nested strings in your data using dot notation\n\n```js\nheaders = [\n  { label: 'First Name', key: 'details.firstName' },\n  { label: 'Last Name', key: 'details.lastName' },\n  { label: 'Job', key: 'job' },\n];\n\ndata = [\n  { details: { firstName: 'Ahmed', lastName: 'Tomi' }, job: 'manager'},\n  { details: { firstName: 'John', lastName: 'Jones' }, job: 'developer'},\n];\n```\nNote: if at any point the nested keys passed do not exist then looks for key with dot notation in the object.\n\n### - **separator** Props:\n\nFollowing a request to add [this feature](https://github.com/react-csv/react-csv/issues/3) , from `1.0.1` release, `react-csv` supports `separator` props which is equals by default a comma `,` .\n\n```js\nimport { CSVLink } from \"react-csv\";\n\n\u003cCSVLink data={array} separator={\";\"}\u003e\n    Download me\n\u003c/CSVLink\u003e\n\n/*\n    \"foo\";\"bar\"\n    \"a\";\"b\"\n */\n```\n\n### - **enclosingCharacter** Props:\n\nFollowing a request to add [this feature](https://github.com/react-csv/react-csv/issues/68), `react-csv` supports an `enclosingCharacter` prop which defaults to `\"`.\n\n\n```js\nimport {CSVLink} from 'react-csv';\n\n\u003cCSVLink data={array} enclosingCharacter={`'`}\u003e\n    Download me\n\u003c/CSVLink\u003e\n\n/*\n    'foo','bar'\n    'a','b'\n */\n\n```\n\n## 1. CSVLink Component:\n\nIt renders a hyperlink and clicking on it will trigger the download action of the CSV document.\n\nIt does not accept only `data` and `headers` props, but it also renders all props of `HTMLAnchor` tag. (className, target,....)\n\n### - **filename** Props:\n\n`filename` is another props restricted to `CSVLink`. It specifies the filename of the downloaded CSV.\n\n**example**\n\n```js\nimport { CSVLink } from \"react-csv\";\n\n\u003cCSVLink\n  data={data}\n  filename={\"my-file.csv\"}\n  className=\"btn btn-primary\"\n  target=\"_blank\"\n\u003e\n  Download me\n\u003c/CSVLink\u003e;\n```\n\n### - **onClick** Props:\n\n`onClick` is another props restricted to `CSVLink`.\n\nIf it is defined, it means 3 things:\n\n1 - It will run at the top of the click handling logic.\n\n2 - [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.\n\n3 - [Async] If it is async, \"done\" argument must be called if you want to invoke the handling of the component. (check examples below)\n\n4 - [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.\n\n**examples**\n\n1. 🔬 Sync + Proceed\n\n```js\nimport { CSVLink } from \"react-csv\";\n\n\u003cCSVLink\n  data={data}\n  onClick={() =\u003e {\n    console.log(\"You click the link\"); // 👍🏻 Your click handling logic\n  }}\n\u003e\n  Download me\n\u003c/CSVLink\u003e;\n```\n\n2. 🔬 Sync + Don't Proceed\n\n```js\nimport { CSVLink } from \"react-csv\";\n\n\u003cCSVLink\n  data={data}\n  onClick={event =\u003e {\n    console.log(\"You click the link\");\n    return false; // 👍🏻 You are stopping the handling of component\n  }}\n\u003e\n  Download me\n\u003c/CSVLink\u003e;\n```\n\n3. 🔬 Async + Proceed\n\n```js\nimport { CSVLink } from \"react-csv\";\n\n\u003cCSVLink\n  data={data}\n  asyncOnClick={true}\n  onClick={(event, done) =\u003e {\n    axios.post(\"/spy/user\").then(() =\u003e {\n      done(); // REQUIRED to invoke the logic of component\n    });\n  }}\n\u003e\n  Download me\n\u003c/CSVLink\u003e;\n```\n\n4. 🔬 Async + Don't Proceed\n\n```js\nimport { CSVLink } from \"react-csv\";\n\n\u003cCSVLink\n  data={data}\n  asyncOnClick={true}\n  onClick={(event, done) =\u003e {\n    axios.post(\"/spy/user\").then(() =\u003e {\n      done(false); // Don't Proceed\n    });\n  }}\n\u003e\n  Download me\n\u003c/CSVLink\u003e;\n```\n\n- 🔬 Async + data function\n\n```js\nimport { CSVLink } from \"react-csv\";\n\nexport default class DownloadUserCSVButton extends React.Component {\n  constructor(props: {}) {\n      super(props);\n\n      this.state = {\n        listOfUsers: [],\n        loading: false\n      };\n  }\n\n  getUsers = (event, done) =\u003e {\n    if(!this.state.loading) {\n      this.setState({\n        loading: true\n      });\n      axios.get(\"/api/users\").then((userListJson) =\u003e {\n        this.setState({\n          listOfUsers: userListJson,\n          loading: false\n        });\n        done(true); // Proceed and get data from dataFromListOfUsersState function\n      }).catch(() =\u003e {\n        this.setState({\n          loading: false\n        });\n        done(false);\n      });\n    }\n  }\n\n  dataFromListOfUsersState = () =\u003e {\n    return this.state.listOfUsers;\n  }\n\n  render() {\n    const {loading} = this.state;\n    return \u003cCSVLink\n      data={this.dataFromListOfUsersState}\n      asyncOnClick={true}\n      onClick={this.getUsers}\n    \u003e\n      {loading ? 'Loading csv...' : 'Download me'}\n    \u003c/CSVLink\u003e;\n  }\n}\n\n```\n\n## 2. CSVDownload Component:\n\nIt triggers downloading ONLY on mounting the component. so , be careful to render this component whenever it is needed.\n\nIt 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 :\n\n```js\nwindow.open(ARG0, target, specs, replace);\n```\n\nThus, `target`, `specs` and `replace` Props are available .\n\n**example**\n\n```js\nimport { CSVDownload } from \"react-csv\";\n\n\u003cCSVDownload data={data} target=\"_blank\" /\u003e;\n```\n\nFor non-node developers, they have to use CDN version :\n\n```html\n \u003cscript src=\"https://cdn.rawgit.com/abdennour/react-csv/6424b500/cdn/react-csv-latest.min.js\" type=\"text/javascript\"\u003e\u003c/script\u003e\n\n \u003cscript type=\"text/babel\"\u003e\n   const {CSVDownload, CSVLink} = ReactCSV;// or window.ReactCSV\n\n   const element= (\u003cCSVDownload data={data} target=\"_blank\" /\u003e);\n\n   ReactDOM.render(element, document.querySelector('#app'));\n \u003c/script\u003e\n```\n\n# Contribution :\n\n- Unit-tests must cover at least 90% of code .\n\n- Write documentation of the new class, function, method, attribute ..so on.. following JSDoc syntax.\n\n- Add an example for the new feature to `sample-site`.\n\n- `docker-compose run --rm npm start` runs the [`sample-site`](sample-site/)\n\n- `docker-compose run --rm npm run docgen` generates documentation in HTML output.\n\n- `docker-compose run --rm npm run cdn` generate a bundle to be used as CDN\n\n# Donation\n\nIf this project help you reduce time to develop, you can give me a cup of coffee 🍵 :)\n\n[![paypal](https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif)](https://www.paypal.me/AbdennourT/2)\n","funding_links":["https://github.com/sponsors/abdennour","https://github.com/sponsors/mccabemj","https://www.paypal.me/AbdennourT/10","https://www.paypal.me/AbdennourT/2"],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freact-csv%2Freact-csv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freact-csv%2Freact-csv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freact-csv%2Freact-csv/lists"}