brighthr-react-spreadsheet-import

React spreadsheet import for xlsx and csv files with column matching and validation

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
brighthr-react-spreadsheet-import
9291.0.143 months ago4 months agoMinified + gzip package size for brighthr-react-spreadsheet-import in KB

Readme

RSI react-spreadsheet-import โšก๏ธ
GitHub Workflow Status GitHub npm

A component used for importing XLS / XLSX / CSV documents built with Chakra UI. Import flow combines:
  • ๐Ÿ“ฅ Uploader
  • โš™๏ธ Parser
  • ๐Ÿ“Š File preview
  • ๐Ÿงช UI for column mapping
  • โœ UI for validating and editing data
โœจ Demo โœจ

Features

  • Custom styles - edit Chakra UI theme to match your project's styles ๐ŸŽจ
  • Custom validation rules - make sure valid data is being imported, easily spot and correct errors
  • Hooks - alter raw data after upload or make adjustments on data changes
  • Auto-mapping columns - automatically map most likely value to your template values, e.g. name -> firstName

rsi-preview

Figma

We provide full figma designs. You can copy the designs here

Getting started

```sh npm i react-spreadsheet-import ``` Using the component: (it's up to you when the flow is open and what you do on submit with the imported data) ```tsx import { ReactSpreadsheetImport } from "react-spreadsheet-import"; ```

Required Props

```tsx // Determines if modal is visible. isOpen: Boolean // Called when flow is closed without reaching submit. onClose: () => void // Called after user completes the flow. Provides data array, where data keys matches your field keys. onSubmit: (data) => void ```

Fields

Fields describe what data you are trying to collect. ```tsx const fields = {
// Visible in table header and when matching columns.
label: "Name",
// This is the key used for this field when we call onSubmit.
key: "name",
// Allows for better automatic column matching. Optional.
alternateMatches: ["first name", "first"],
// Used when editing and validating information.
fieldType: {
// There are 3 types - "input" / "checkbox" / "select".
type: "input",
},
// Used in the first step to provide an example of what data is expected in this field. Optional.
example: "Stephanie",
// Can have multiple validations that are visible in Validation Step table.
validations: [
{
// Can be "required" / "unique" / "regex"
rule: "required",
errorMessage: "Name is required",
// There can be "info" / "warning" / "error" levels. Optional. Default "error".
level: "error",
},
],
},
as const ```

Optional Props

Hooks

You can transform and validate data with custom hooks. There are 3 hooks that have different performance tradeoffs:
  • initialHook - runs only once after column matching. Operations that should run once should be done here.
  • tableHook - runs at the start and on any change. Runs on all rows. Very expensive, but can change rows that depend on other rows.
  • rowHook - runs at the start and on any row change. Runs only on the rows changed. Fastest, most validations and transformations should be done here.
Example: ```tsx {
// Validation
if (data.name === "John") {
addError("name", { message: "No Johns allowed", level: "info" })
}
// Transformation
return { ...data, name: "Not John" }
// Sorry John
}} /> ```

Other optional props

```tsx // Allows submitting with errors. Default: true allowInvalidSubmit?: boolean // Translations for each text. See customisation bellow translations?: object // Theme configuration passed to underlying Chakra-UI. See customisation bellow customTheme?: object // Specifies maximum number of rows for a single import maxRecords?: number // Maximum upload filesize (in bytes) maxFileSize?: number // Automatically map imported headers to specified fields if possible. Default: true autoMapHeaders?: boolean // Headers matching accuracy: 1 for strict and up for more flexible matching. Default: 2 autoMapDistance?: number ```

Customisation

Customising styles (colors, fonts)

You can see default theme we use here. Your override should match this object's structure. There are 3 ways you can style the component: 1.) Change theme colors globally ```jsx
<ReactSpreadsheetImport
{...mockRsiValues}
isOpen={isOpen}
onClose={onClose}
onSubmit={setData}
customTheme={{
colors: {
background: 'white',
...
rsi: {
// your brand colors should go here
50: '...'
...
500: 'teal',
...
900: "...",
},
},
}}
/>
``` Screenshot 2022-04-13 at 10 24 34 2.) Change all components of the same type, like all Buttons, at the same time ```jsx
<ReactSpreadsheetImport
{...mockRsiValues}
isOpen={isOpen}
onClose={onClose}
onSubmit={setData}
customTheme={{
components: {
Button: {
baseStyle: {
borderRadius: "none",
},
defaultProps: {
colorScheme: "yellow",
},
},
},
}}
/>
``` Screenshot 2022-04-13 at 11 04 30 3.) Change components specifically in each Step. ```jsx
<ReactSpreadsheetImport
{...mockRsiValues}
isOpen={isOpen}
onClose={onClose}
onSubmit={setData}
customTheme={{
components: {
UploadStep: {
baseStyle: {
dropzoneButton: {
bg: "red",
},
},
},
},
}}
/>
``` Screenshot 2022-04-13 at 10 21 58 Underneath we use Chakra-UI, you can send in a custom theme for us to apply. Read more about themes here

Changing text (translations)

You can change any text in the flow: ```tsx uploadStep: {
title: "Upload Employees",
},
}} /> ``` You can see all the translation keys here

VS other libraries

Flatfile vs react-spreadsheet-import and Dromo vs react-spreadsheet-import: | | RSI | Flatfile | Dromo | |------------------------------------|----------------|-------------|-------------| | Licence | MIT | Proprietary | Proprietary | | Price | Free | Paid | Paid | | Support | Github Issues | Enterprise | Enterprise | | Self-host | Yes | Paid | Paid | | Hosted solution | In development | Yes | No | | On-prem deployment | N/A | Yes | Yes | | Hooks | Yes | Yes | Yes | | Automatic header matching | Yes | Yes | Yes | | Data validation | Yes | Yes | Yes | | Custom styling | Yes | Yes | Yes | | Translations | Yes | Yes | No | | Trademarked words Data Hooks | No | Yes | No | React-spreadsheet-import can be used as a free and open-source alternative to Flatfile and Dromo.

Contributing

Feel free to open issues if you have any questions or notice bugs. If you want different component behaviour, consider forking the project.

Credits

Created by Ugnis. Julita Kriauciunaite and Karolis Masiulis. You can contact us at info@ugnis.com