{"id":13422325,"url":"https://github.com/UgnisSoftware/react-spreadsheet-import","last_synced_at":"2025-03-15T12:30:38.965Z","repository":{"id":37084514,"uuid":"452637077","full_name":"UgnisSoftware/react-spreadsheet-import","owner":"UgnisSoftware","description":"Import flow for Excel (.xlsx) and CSV file with automated column matching and validation.","archived":false,"fork":false,"pushed_at":"2024-08-23T08:23:52.000Z","size":30887,"stargazers_count":446,"open_issues_count":32,"forks_count":118,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-10-29T15:41:10.130Z","etag":null,"topics":["csv","data-import","excel","excel-import","import","import-flow","react","sheet","sheet-import","upload","xls","xlsx"],"latest_commit_sha":null,"homepage":"https://ugnissoftware.github.io/react-spreadsheet-import/iframe.html?id=react-spreadsheet-import--basic\u0026args=\u0026viewMode=story","language":"TypeScript","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/UgnisSoftware.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2022-01-27T10:29:24.000Z","updated_at":"2024-10-28T17:16:08.000Z","dependencies_parsed_at":"2024-01-16T00:18:56.748Z","dependency_job_id":"0ec1ab5d-0eb1-4c39-870c-4a7b74ce5316","html_url":"https://github.com/UgnisSoftware/react-spreadsheet-import","commit_stats":{"total_commits":243,"total_committers":10,"mean_commits":24.3,"dds":"0.40740740740740744","last_synced_commit":"feecfd0dd400d18c52ea36331bb8cdb1141246ff"},"previous_names":[],"tags_count":43,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UgnisSoftware%2Freact-spreadsheet-import","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UgnisSoftware%2Freact-spreadsheet-import/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UgnisSoftware%2Freact-spreadsheet-import/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UgnisSoftware%2Freact-spreadsheet-import/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/UgnisSoftware","download_url":"https://codeload.github.com/UgnisSoftware/react-spreadsheet-import/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243730925,"owners_count":20338737,"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","data-import","excel","excel-import","import","import-flow","react","sheet","sheet-import","upload","xls","xlsx"],"created_at":"2024-07-30T23:00:41.658Z","updated_at":"2025-03-15T12:30:38.627Z","avatar_url":"https://github.com/UgnisSoftware.png","language":"TypeScript","readme":"\u003ch1 align=\"center\"\u003eRSI react-spreadsheet-import ⚡️\u003c/h1\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \n![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/UgnisSoftware/react-spreadsheet-import/test.yaml)\n![GitHub](https://img.shields.io/github/license/UgnisSoftware/react-spreadsheet-import) [![npm](https://img.shields.io/npm/v/react-spreadsheet-import)](https://www.npmjs.com/package/react-spreadsheet-import)\n  \n\u003c/div\u003e\n\u003cbr /\u003e\n\nA component used for importing XLS / XLSX / CSV documents built with [**Chakra UI**](https://chakra-ui.com). Import flow combines:\n\n- 📥 Uploader\n- ⚙️ Parser\n- 📊 File preview\n- 🧪 UI for column mapping\n- ✏ UI for validating and editing data\n\n✨ [**Demo**](https://ugnissoftware.github.io/react-spreadsheet-import/iframe.html?id=react-spreadsheet-import--basic\u0026args=\u0026viewMode=story) ✨\n\u003cbr /\u003e\n\n## Features\n\n- Custom styles - edit Chakra UI theme to match your project's styles 🎨\n- Custom validation rules - make sure valid data is being imported, easily spot and correct errors\n- Hooks - alter raw data after upload or make adjustments on data changes\n- Auto-mapping columns - automatically map most likely value to your template values, e.g. `name` -\u003e `firstName`\n  \u003cbr /\u003e\n\n![rsi-preview](https://user-images.githubusercontent.com/45755753/159503528-90aacb69-128f-4ece-b45b-ab97d403a9d3.gif)\n\n## Figma\n\nWe provide full figma designs. You can copy the designs\n[here](https://www.figma.com/community/file/1080776795891439629)\n\n## Getting started\n\n```sh\nnpm i react-spreadsheet-import\n```\n\nUsing the component: (it's up to you when the flow is open and what you do on submit with the imported data)\n\n```tsx\nimport { ReactSpreadsheetImport } from \"react-spreadsheet-import\";\n\n\u003cReactSpreadsheetImport isOpen={isOpen} onClose={onClose} onSubmit={onSubmit} fields={fields} /\u003e\n```\n\n## Required Props\n\n```tsx\n  // Determines if modal is visible.\n  isOpen: Boolean\n  // Called when flow is closed without reaching submit.\n  onClose: () =\u003e void\n  // Called after user completes the flow. Provides data array, where data keys matches your field keys. \n  onSubmit: (data, file) =\u003e void | Promise\u003cany\u003e\n```\n\n### Fields\n\nFields describe what data you are trying to collect.\n\n```tsx\nconst fields = [\n  {\n    // Visible in table header and when matching columns.\n    label: \"Name\",\n    // This is the key used for this field when we call onSubmit.\n    key: \"name\",\n    // Allows for better automatic column matching. Optional.\n    alternateMatches: [\"first name\", \"first\"],\n    // Used when editing and validating information.\n    fieldType: {\n      // There are 3 types - \"input\" / \"checkbox\" / \"select\".\n      type: \"input\",\n    },\n    // Used in the first step to provide an example of what data is expected in this field. Optional.\n    example: \"Stephanie\",\n    // Can have multiple validations that are visible in Validation Step table.\n    validations: [\n      {\n        // Can be \"required\" / \"unique\" / \"regex\"\n        rule: \"required\",\n        errorMessage: \"Name is required\",\n        // There can be \"info\" / \"warning\" / \"error\" levels. Optional. Default \"error\".\n        level: \"error\",\n      },\n    ],\n  },\n] as const\n```\n\n## Optional Props\n\n### Hooks\n\nYou can transform and validate data with custom hooks. There are hooks after each step:\n\n- **uploadStepHook** - runs only once after uploading the file.\n- **selectHeaderStepHook** - runs only once after selecting the header row in spreadsheet.\n- **matchColumnsStepHook** - runs only once after column matching. Operations on data that are expensive should be done here.\n\nThe last step - validation step has 2 unique hooks that run only in that step with different performance tradeoffs:\n\n- **tableHook** - runs at the start and on any change. Runs on all rows. Very expensive, but can change rows that depend on other rows.\n- **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.\n\nExample:\n\n```tsx\n\u003cReactSpreadsheetImport\n  rowHook={(data, addError) =\u003e {\n    // Validation\n    if (data.name === \"John\") {\n      addError(\"name\", { message: \"No Johns allowed\", level: \"info\" })\n    }\n    // Transformation\n    return { ...data, name: \"Not John\" }\n    // Sorry John\n  }}\n/\u003e\n```\n\n### Initial state\n\nIn rare case when you need to skip the beginning of the flow, you can start the flow from any of the steps.\n\n- **initialStepState** - initial state of component that will be rendered on load. \n\n```tsx\n  initialStepState?: StepState\n  \n  type StepState =\n    | {\n        type: StepType.upload\n      }\n    | {\n        type: StepType.selectSheet\n        workbook: XLSX.WorkBook\n      }\n    | {\n        type: StepType.selectHeader\n        data: RawData[]\n      }\n    | {\n        type: StepType.matchColumns\n        data: RawData[]\n        headerValues: RawData\n      }\n    | {\n        type: StepType.validateData\n        data: any[]\n      }\n\n  type RawData = Array\u003cstring | undefined\u003e\n\n  // XLSX.workbook type is native to SheetJS and can be viewed here: https://github.com/SheetJS/sheetjs/blob/83ddb4c1203f6bac052d8c1608b32fead02ea32f/types/index.d.ts#L269\n```\n\nExample:\n\n```tsx\nimport { ReactSpreadsheetImport, StepType } from \"react-spreadsheet-import\";\n\n\u003cReactSpreadsheetImport\n  initialStepState={{\n    type: StepType.matchColumns,\n    data: [\n      [\"Josh\", \"2\"],\n      [\"Charlie\", \"3\"],\n      [\"Lena\", \"50\"],\n    ],\n    headerValues: [\"name\", \"age\"],\n  }}\n/\u003e\n```\n\n### Dates and time\n\nExcel stores dates and times as numbers - offsets from an epoch. When reading xlsx files SheetJS provides date formatting helpers.\n**Default date import format** is `yyyy-mm-dd`. Date parsing with SheetJS sometimes yields unexpected results, therefore thorough date validations are recommended.\n\n- **dateFormat** - sets SheetJS `dateNF` option. Can be used to format dates when importing sheet data.\n- **parseRaw** - sets SheetJS `raw` option. If `true`, date formatting will be applied to XLSX date fields only. Default is `true`\n\nCommon date-time formats can be viewed [here](https://docs.sheetjs.com/docs/csf/features/dates/#date-and-time-number-formats).\n\n### Other optional props\n\n```tsx\n  // Allows submitting with errors. Default: true\n  allowInvalidSubmit?: boolean\n  // Translations for each text. See customisation bellow\n  translations?: object\n  // Theme configuration passed to underlying Chakra-UI. See customisation bellow\n  customTheme?: object\n  // Specifies maximum number of rows for a single import\n  maxRecords?: number\n  // Maximum upload filesize (in bytes)\n  maxFileSize?: number\n  // Automatically map imported headers to specified fields if possible. Default: true\n  autoMapHeaders?: boolean\n  // When field type is \"select\", automatically match values if possible. Default: false\n  autoMapSelectValues?: boolean\n  // Headers matching accuracy: 1 for strict and up for more flexible matching. Default: 2\n  autoMapDistance?: number\n  // Enable navigation in stepper component and show back button. Default: false\n  isNavigationEnabled?: boolean\n```\n\n## Customisation\n\n### Customising styles (colors, fonts)\n\nYou can see default theme we use [here](https://github.com/UgnisSoftware/react-spreadsheet-import/blob/master/src/theme.ts). Your override should match this object's structure.\n\nThere are 3 ways you can style the component:\n\n1.) Change theme colors globally\n\n```jsx\n    \u003cReactSpreadsheetImport\n        {...mockRsiValues}\n        isOpen={isOpen}\n        onClose={onClose}\n        onSubmit={setData}\n        customTheme={{\n          colors: {\n            background: 'white',\n            ...\n            rsi: {\n              // your brand colors should go here\n              50: '...'\n              ...\n              500: 'teal',\n              ...\n              900: \"...\",\n            },\n          },\n        }}\n      /\u003e\n```\n\n\u003cimg width=\"1189\" alt=\"Screenshot 2022-04-13 at 10 24 34\" src=\"https://user-images.githubusercontent.com/5903616/163123718-15c05ad8-243b-4a81-8141-c47216047468.png\"\u003e\n\n2.) Change all components of the same type, like all Buttons, at the same time\n\n```jsx\n\u003cReactSpreadsheetImport\n  {...mockRsiValues}\n  isOpen={isOpen}\n  onClose={onClose}\n  onSubmit={setData}\n  customTheme={{\n    components: {\n      Button: {\n        baseStyle: {\n          borderRadius: \"none\",\n        },\n        defaultProps: {\n          colorScheme: \"yellow\",\n        },\n      },\n    },\n  }}\n/\u003e\n```\n\n\u003cimg width=\"1191\" alt=\"Screenshot 2022-04-13 at 11 04 30\" src=\"https://user-images.githubusercontent.com/5903616/163130213-82f955b4-5081-49e0-8f43-8857d480dacd.png\"\u003e\n \n3.) Change components specifically in each Step.\n```jsx\n    \u003cReactSpreadsheetImport\n        {...mockRsiValues}\n        isOpen={isOpen}\n        onClose={onClose}\n        onSubmit={setData}\n        customTheme={{\n          components: {\n            UploadStep: {\n              baseStyle: {\n                dropzoneButton: {\n                  bg: \"red\",\n                },\n              },\n            },\n          },\n        }}\n      /\u003e\n```\n\u003cimg width=\"1182\" alt=\"Screenshot 2022-04-13 at 10 21 58\" src=\"https://user-images.githubusercontent.com/5903616/163123694-5b79179e-037e-4f9d-b1a9-6078f758bb7e.png\"\u003e\n\nUnderneath we use Chakra-UI, you can send in a custom theme for us to apply. Read more about themes [here](https://chakra-ui.com/docs/styled-system/theming/theme)\n\n### Changing text (translations)\n\nYou can change any text in the flow:\n\n```tsx\n\u003cReactSpreadsheetImport\n  translations={{\n    uploadStep: {\n      title: \"Upload Employees\",\n    },\n  }}\n/\u003e\n```\n\nYou can see all the translation keys [here](https://github.com/UgnisSoftware/react-spreadsheet-import/blob/master/src/translationsRSIProps.ts)\n\n## VS other libraries\n\nFlatfile vs react-spreadsheet-import and Dromo vs react-spreadsheet-import:\n\n|                                | RSI            | Flatfile    | Dromo       |\n| ------------------------------ | -------------- | ----------- | ----------- |\n| Licence                        | MIT            | Proprietary | Proprietary |\n| Price                          | Free           | Paid        | Paid        |\n| Support                        | Github Issues  | Enterprise  | Enterprise  |\n| Self-host                      | Yes            | Paid        | Paid        |\n| Hosted solution                | In development | Yes         | Yes         |\n| On-prem deployment             | N/A            | Yes         | Yes         |\n| Hooks                          | Yes            | Yes         | Yes         |\n| Automatic header matching      | Yes            | Yes         | Yes         |\n| Data validation                | Yes            | Yes         | Yes         |\n| Custom styling                 | Yes            | Yes         | Yes         |\n| Translations                   | Yes            | Yes         | Yes         |\n| Trademarked words `Data Hooks` | No             | Yes         | No          |\n\nReact-spreadsheet-import can be used as a free and open-source alternative to Flatfile and Dromo.\n\n## Contributing\n\nFeel free to open issues if you have any questions or notice bugs. If you want different component behaviour, consider forking the project.\n\n## Credits\n\nCreated by Ugnis. [Julita Kriauciunaite](https://github.com/JulitorK) and [Karolis Masiulis](https://github.com/masiulis). You can contact us at `info@ugnis.com`\n","funding_links":[],"categories":["🛠️ Tools"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FUgnisSoftware%2Freact-spreadsheet-import","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FUgnisSoftware%2Freact-spreadsheet-import","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FUgnisSoftware%2Freact-spreadsheet-import/lists"}