--- title: ReactJS pagination_prev: demos/index pagination_next: demos/grid/index sidebar_position: 1 --- import current from '/version.js'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock'; ReactJS is a JS library for building user interfaces. This demo tries to cover common React data flow ideas and strategies. React familiarity is assumed. Other demos cover general React deployments, including: - [Static Site Generation powered by NextJS](/docs/demos/static/nextjs) - [iOS and Android applications powered by React Native](/docs/demos/mobile/reactnative) - [Desktop application powered by React Native Windows + macOS](/docs/demos/desktop/reactnative) - [React Data Grid UI component](/docs/demos/grid/rdg) - [Glide Data Grid UI component](/docs/demos/grid/gdg) ## Installation [The "Frameworks" section](/docs/getting-started/installation/frameworks) covers installation with Yarn and other package managers. The library can be imported directly from JS or JSX code with: ```js import { read, utils, writeFile } from 'xlsx'; ``` ## Internal State The various SheetJS APIs work with various data shapes. The preferred state depends on the application. ### Array of Objects Typically, some users will create a spreadsheet with source data that should be loaded into the site. This sheet will have known columns. #### State The example [presidents sheet](https://sheetjs.com/pres.xlsx) has one header row with "Name" and "Index" columns. The natural JS representation is an object for each row, using the values in the first rows as keys:
SpreadsheetState
![`pres.xlsx` data](pathname:///pres.png) ```js [ { Name: "Bill Clinton", Index: 42 }, { Name: "GeorgeW Bush", Index: 43 }, { Name: "Barack Obama", Index: 44 }, { Name: "Donald Trump", Index: 45 }, { Name: "Joseph Biden", Index: 46 } ] ```
The React `useState` hook can configure the state: ```ts import { useState } from 'react'; /* the component state is an array of objects */ const [pres, setPres] = useState([]); ``` ```ts import { useState } from 'react'; /* the component state is an array of objects */ const [pres, setPres] = useState([]); ``` When the spreadsheet header row is known ahead of time, row typing is possible: ```ts import { useState } from 'react'; interface President { Name: string; Index: number; } /* the component state is an array of presidents */ const [pres, setPres] = useState([]); ``` :::caution pass The types are informative. They do not enforce that worksheets include the named columns. A runtime data validation library should be used to verify the dataset. When the file header is not known in advance, `any` should be used. ::: #### Updating State The [`read`](/docs/api/parse-options) and [`sheet_to_json`](/docs/api/utilities/array#array-output) functions simplify state updates. They are best used in the function bodies of `useEffect` and `useCallback` hooks. A `useEffect` hook can download and update state when a person loads the site: ```mermaid flowchart LR url[(Remote\nFile)] ab[(Data\nArrayBuffer)] wb(SheetJS\nWorkbook) ws(SheetJS\nWorksheet) aoo(array of\nobjects) state((component\nstate)) url --> |fetch\n\n| ab ab --> |read\n\n| wb wb --> |wb.Sheets\nselect sheet| ws ws --> |sheet_to_json\n\n| aoo aoo --> |setPres\nfrom `setState`| state ``` ```ts import { useEffect } from 'react'; import { read, utils } from 'xlsx'; /* Fetch and update the state once */ useEffect(() => { (async() => { /* Download file */ const f = await (await fetch("https://sheetjs.com/pres.xlsx")).arrayBuffer(); // highlight-start const wb = read(f); // parse the array buffer const ws = wb.Sheets[wb.SheetNames[0]]; // get the first worksheet const data = utils.sheet_to_json(ws); // generate objects setPres(data); // update state // highlight-end })(); }, []); ``` ```ts import { useEffect } from 'react'; import { read, utils } from 'xlsx'; /* Fetch and update the state once */ useEffect(() => { (async() => { /* Download file */ const f = await (await fetch("https://sheetjs.com/pres.xlsx")).arrayBuffer(); // highlight-start const wb = read(f); // parse the array buffer const ws = wb.Sheets[wb.SheetNames[0]]; // get the first worksheet const data: President[] = utils.sheet_to_json(ws); // generate objects setPres(data); // update state // highlight-end })(); }, []); ``` #### Rendering Data Components typically render HTML tables from arrays of objects. The `` table row elements are typically generated by mapping over the state array, as shown in the example JSX code: ```jsx title="Example JSX for displaying arrays of objects" {/* The `thead` section includes the table header row */} {/* The `tbody` section includes the data rows */} {/* generate row (TR) for each president */} // highlight-start {pres.map(row => ( {/* Generate cell (TD) for name / index */} ))} // highlight-end
NameIndex
{row.Name} {row.Index}
``` #### Exporting Data The [`writeFile`](/docs/api/write-options) and [`json_to_sheet`](/docs/api/utilities/array#array-of-objects-input) functions simplify exporting data. They are best used in the function bodies of `useCallback` hooks attached to button or other elements. A callback can generate a local file when a user clicks a button: ```mermaid flowchart LR state((component\nstate)) ws(SheetJS\nWorksheet) wb(SheetJS\nWorkbook) file[(XLSX\nexport)] state --> |json_to_sheet\n\n| ws ws --> |book_new\nbook_append_sheet| wb wb --> |writeFile\n\n| file ``` ```ts import { useCallback } from 'react'; import { utils, writeFile } from 'xlsx'; /* get state data and export to XLSX */ const exportFile = useCallback(() => { /* generate worksheet from state */ // highlight-next-line const ws = utils.json_to_sheet(pres); /* create workbook and append worksheet */ const wb = utils.book_new(); utils.book_append_sheet(wb, ws, "Data"); /* export to XLSX */ writeFile(wb, "SheetJSReactAoO.xlsx"); }, [pres]); ``` #### Complete Component This complete component example fetches a test file and displays the contents in a HTML table. When the export button is clicked, a callback will export a file: ```jsx title="src/SheetJSReactAoO.js" import React, { useCallback, useEffect, useState } from "react"; import { read, utils, writeFileXLSX } from 'xlsx'; export default function SheetJSReactAoO() { /* the component state is an array of presidents */ const [pres, setPres] = useState([]); /* Fetch and update the state once */ useEffect(() => { (async() => { const f = await (await fetch("https://sheetjs.com/pres.xlsx")).arrayBuffer(); // highlight-start const wb = read(f); // parse the array buffer const ws = wb.Sheets[wb.SheetNames[0]]; // get the first worksheet const data = utils.sheet_to_json(ws); // generate objects setPres(data); // update state // highlight-end })(); }, []); /* get state data and export to XLSX */ const exportFile = useCallback(() => { // highlight-next-line const ws = utils.json_to_sheet(pres); const wb = utils.book_new(); utils.book_append_sheet(wb, ws, "Data"); writeFileXLSX(wb, "SheetJSReactAoO.xlsx"); }, [pres]); return ( { /* generate row for each president */ // highlight-start pres.map(pres => ()) // highlight-end }
NameIndex
{pres.Name} {pres.Index}
); } ```
How to run the example (click to show) :::note This demo was last run on 2023 February 28 using `create-react-app@5.0.1` and `react-scripts@5.0.1`. ::: 1) Run `npx create-react-app@5.0.1 --scripts-version=5.0.1 sheetjs-react`. 2) Install the SheetJS dependency and start the dev server: {`\ cd sheetjs-react npm i npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz npm start`} 3) Open a web browser and access the displayed URL (`http://localhost:3000`) 4) Replace `src/App.js` with the `src/SheetJSReactAoO.js` example. The page will refresh and show a table with an Export button. Click the button and the page will attempt to download `SheetJSReactAoA.xlsx`. 5) Build the site with `npm run build`, then test with `npx http-server build`. Access `http://localhost:8080` with a web browser to test the bundled site.
### HTML The main disadvantage of the Array of Objects approach is the specific nature of the columns. For more general use, passing around an Array of Arrays works. However, this does not handle merge cells well! The `sheet_to_html` function generates HTML that is aware of merges and other worksheet features. React `dangerouslySetInnerHTML` attribute allows code to set the `innerHTML` attribute, effectively inserting the code into the page. In this example, the component attaches a `ref` to the `DIV` container. During export, the first `TABLE` child element can be parsed with `table_to_book` to generate a workbook object. ```jsx title="src/SheetJSReactHTML.js" import React, { useCallback, useEffect, useRef, useState } from "react"; import { read, utils, writeFileXLSX } from 'xlsx'; export default function SheetJSReactHTML() { /* the component state is an HTML string */ const [__html, setHtml] = useState(""); /* the ref is used in export */ const tbl = useRef(null); /* Fetch and update the state once */ useEffect(() => { (async() => { const f = await (await fetch("https://sheetjs.com/pres.xlsx")).arrayBuffer(); const wb = read(f); // parse the array buffer const ws = wb.Sheets[wb.SheetNames[0]]; // get the first worksheet // highlight-start const data = utils.sheet_to_html(ws); // generate HTML setHtml(data); // update state // highlight-end })(); }, []); /* get live table and export to XLSX */ const exportFile = useCallback(() => { // highlight-start const elt = tbl.current.getElementsByTagName("TABLE")[0]; const wb = utils.table_to_book(elt); // highlight-end writeFileXLSX(wb, "SheetJSReactHTML.xlsx"); }, [tbl]); return ( <> // highlight-next-line
); } ```
How to run the example (click to show) :::note This demo was last run on 2023 February 28 using `create-react-app@5.0.1` and `react-scripts@5.0.1`. ::: 1) Run `npx create-react-app@5.0.1 --scripts-version=5.0.1 sheetjs-react`. 2) Install the SheetJS dependency and start the dev server: {`\ cd sheetjs-react npm i npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz npm start`} 3) Open a web browser and access the displayed URL (`http://localhost:3000`) 4) Replace `src/App.js` with the `src/SheetJSReactHTML.js` example. The page will refresh and show a table with an Export button. Click the button and the page will attempt to download `SheetJSReactHTML.xlsx`. 5) Build the site with `npm run build`, then test with `npx http-server build`. Access `http://localhost:8080` with a web browser to test the bundled site.
### Rows and Columns Some data grids and UI components split worksheet state in two parts: an array of column attribute objects and an array of row objects. The former is used to generate column headings and for indexing into the row objects. The safest approach is to use an array of arrays for state and to generate column objects that map to A1-Style column headers. The [React Data Grid demo](/docs/demos/grid#rows-and-columns-state) uses this approach with the following column and row structure: ```js /* rows are generated with a simple array of arrays */ const rows = utils.sheet_to_json(worksheet, { header: 1 }); /* column objects are generated based on the worksheet range */ const range = utils.decode_range(ws["!ref"]||"A1"); const columns = Array.from({ length: range.e.c + 1 }, (_, i) => ({ /* for an array of arrays, the keys are "0", "1", "2", ... */ key: String(i), /* column labels: encode_col translates 0 -> "A", 1 -> "B", 2 -> "C", ... */ name: XLSX.utils.encode_col(i) })); ``` ![Column labels for headers](pathname:///react/cols.png) ## Legacy Deployments [The Standalone Scripts](/docs/getting-started/installation/standalone) play nice with legacy deployments that do not use a bundler. [The legacy demo](pathname:///react/index.html) shows a simple React component transpiled in the browser using Babel standalone library.