react-spreadsheet-import

You can use hooks to alter raw data or perform custom validations at different stages of the import flow:

Step-based Hooks (Run once per step)

• uploadStepHook: Runs once after the file is uploaded.
• selectHeaderStepHook: Runs once after the header row is selected.
• matchColumnsStepHook: Runs once after column mapping. Best for expensive operations.

Validation Step Hooks

• tableHook: Runs at the start and on any change. Runs on all rows. Use this for complex validations where rows depend on each other (expensive).
• rowHook: Runs at the start and on any row change. Runs only on changed rows. Best for most transformations and validations (fast).

<ReactSpreadsheetImport
  rowHook={(data, addError) => {
    // Validation
    if (data.name === "John") {
      addError("name", { message: "No Johns allowed", level: "info" })
    }
    // Transformation
    return { ...data, name: "Not John" }
  }}
/>

The fields prop is an array of objects that describes the data you want to collect. Each field object can include:

• label: The display name in the table header.
• key: The key used in the final data object passed to onSubmit.
• alternateMatches: (Optional) Array of strings to improve automatic column matching.
• fieldType: An object with type (either "input", "checkbox", or "select").
• example: (Optional) A string showing expected data format.
• validations: An array of validation objects with rule ("required", "unique", or "regex"), errorMessage, and level ("info", "warning", or "error", defaulting to "error").

const fields = [
  {
    label: "Name",
    key: "name",
    alternateMatches: ["first name", "first"],
    fieldType: {
      type: "input",
    },
    example: "Stephanie",
    validations: [
      {
        rule: "required",
        errorMessage: "Name is required",
        level: "error",
      },
    ],
  },
] as const

The component uses a set of default properties that control the behavior of the import flow. You can override these by passing your own configuration via the RsiProps object.

Key default behaviors include:

• autoMapHeaders: true: Automatically attempts to map spreadsheet headers to your data keys.
• autoMapSelectValues: false: Does not automatically map select values.
• allowInvalidSubmit: true: Allows the user to proceed even if there are validation errors.
• autoMapDistance: 2: The threshold for automatic header mapping.
• isNavigationEnabled: false: Disables step-by-step navigation by default.
• dateFormat: "yyyy-mm-dd": The default date format used for parsing.
• parseRaw: true: Enables raw parsing of data.

export const defaultRSIProps: Partial<RsiProps<any>> = {
  autoMapHeaders: true,
  autoMapSelectValues: false,
  allowInvalidSubmit: true,
  autoMapDistance: 2,
  isNavigationEnabled: false,
  translations: translations,
  uploadStepHook: async (value) => value,
  selectHeaderStepHook: async (headerValues, data) => ({ headerValues, data }),
  matchColumnsStepHook: async (table) => table,
  dateFormat: "yyyy-mm-dd",
  parseRaw: true,
} as const

You can intercept and transform data at different stages of the import process using step hooks. These hooks are part of the defaultRSIProps and can be overridden in your component configuration:

• uploadStepHook: An async function that receives the uploaded value. Use this to transform the file or data immediately after upload.
• selectHeaderStepHook: An async function that receives headerValues and data. It expects a return object of type { headerValues, data } to allow modification of headers or the dataset during the header selection step.
• matchColumnsStepHook: An async function that receives the table object. Use this to transform the table structure during the column matching step.

const props = {
  uploadStepHook: async (value) => {
    // transform uploaded value
    return value;
  },
  selectHeaderStepHook: async (headerValues, data) => {
    // transform headers or data
    return { headerValues, data };
  },
  matchColumnsStepHook: async (table) => {
    // transform the table
    return table;
  },
};