UgnisSoftware/react-spreadsheet-importPublic

NotificationsYou must be signed in to change notification settings
Fork141
Star509

Import flow for Excel (.xlsx) and CSV file with automated column matching and validation.

ugnissoftware.github.io/react-spreadsheet-import/iframe.html?id=react-spreadsheet-import--basic&args=&viewMode=story

License

MIT license

509 stars 141 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 511 Commits
.github		.github
.storybook		.storybook
e2e		e2e
src		src
static		static
.babelrc.json		.babelrc.json
.eslintignore		.eslintignore
.eslintrc		.eslintrc
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
playwright.config.ts		playwright.config.ts
rollup.config.ts		rollup.config.ts
tsconfig.json		tsconfig.json

Repository files navigation

RSI react-spreadsheet-import ⚡️

A component used for importing XLS / XLSX / CSV documents built withChakra 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

Figma

We provide full figma designs. You can copy the designshere

Getting started

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)

import{ReactSpreadsheetImport}from"react-spreadsheet-import";<ReactSpreadsheetImportisOpen={isOpen}onClose={onClose}onSubmit={onSubmit}fields={fields}/>

Required Props

// 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,file)=>void|Promise<any>

Fields

Fields describe what data you are trying to collect.

constfields=[{// 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",},],},]asconst

Optional Props

Hooks

You can transform and validate data with custom hooks. There are hooks after each step:

uploadStepHook - runs only once after uploading the file.
selectHeaderStepHook - runs only once after selecting the header row in spreadsheet.
matchColumnsStepHook - runs only once after column matching. Operations on data that are expensive should be done here.

The last step - validation step has 2 unique hooks that run only in that step with different performance tradeoffs:

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:

<ReactSpreadsheetImportrowHook={(data,addError)=>{// Validationif(data.name==="John"){addError("name",{message:"No Johns allowed",level:"info"})}// Transformationreturn{ ...data,name:"Not John"}// Sorry John}}/>

Initial state

In rare case when you need to skip the beginning of the flow, you can start the flow from any of the steps.

initialStepState - initial state of component that will be rendered on load.

  initialStepState?:StepStatetypeStepState=|{type:StepType.upload}|{type:StepType.selectSheetworkbook:XLSX.WorkBook}|{type:StepType.selectHeaderdata:RawData[]}|{type:StepType.matchColumnsdata:RawData[]headerValues:RawData}|{type:StepType.validateDatadata:any[]}typeRawData=Array<string|undefined>// XLSX.workbook type is native to SheetJS and can be viewed here: https://github.com/SheetJS/sheetjs/blob/83ddb4c1203f6bac052d8c1608b32fead02ea32f/types/index.d.ts#L269

Example:

import{ReactSpreadsheetImport,StepType}from"react-spreadsheet-import";<ReactSpreadsheetImportinitialStepState={{type:StepType.matchColumns,data:[["Josh","2"],["Charlie","3"],["Lena","50"],],headerValues:["name","age"],}}/>

Dates and time

Excel stores dates and times as numbers - offsets from an epoch. When reading xlsx files SheetJS provides date formatting helpers.Default date import format isyyyy-mm-dd. Date parsing with SheetJS sometimes yields unexpected results, therefore thorough date validations are recommended.

dateFormat - sets SheetJSdateNF option. Can be used to format dates when importing sheet data.
parseRaw - sets SheetJSraw option. Iftrue, date formatting will be applied to XLSX date fields only. Default istrue

Common date-time formats can be viewedhere.

Other optional props

// 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// When field type is "select", automatically match values if possible. Default: false  autoMapSelectValues?:boolean// Headers matching accuracy: 1 for strict and up for more flexible matching. Default: 2  autoMapDistance?:number// Enable navigation in stepper component and show back button. Default: false  isNavigationEnabled?:boolean

Customisation

Customising styles (colors, fonts)

You can see default theme we usehere. Your override should match this object's structure.

There are 3 ways you can style the component:

1.) Change theme colors globally

<ReactSpreadsheetImport{...mockRsiValues}isOpen={isOpen}onClose={onClose}onSubmit={setData}customTheme={{colors:{background:'white',            ...rsi:{// your brand colors should go here50:'...'...500:'teal',              ...900:"...",},},}}/>

2.) Change all components of the same type, like all Buttons, at the same time

<ReactSpreadsheetImport{...mockRsiValues}isOpen={isOpen}onClose={onClose}onSubmit={setData}customTheme={{components:{Button:{baseStyle:{borderRadius:"none",},defaultProps:{colorScheme:"yellow",},},},}}/>

3.) Change components specifically in each Step.

<ReactSpreadsheetImport{...mockRsiValues}isOpen={isOpen}onClose={onClose}onSubmit={setData}customTheme={{components:{UploadStep:{baseStyle:{dropzoneButton:{bg:"red",},},},},}}/>

Underneath we use Chakra-UI, you can send in a custom theme for us to apply. Read more about themeshere

Changing text (translations)

You can change any text in the flow:

<ReactSpreadsheetImporttranslations={{uploadStep:{title:"Upload Employees",},}}/>

You can see all the translation keyshere

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	Yes
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	Yes
Trademarked words`Data Hooks`	No	Yes	No