### Install react-spreadsheet-import

Source: https://github.com/ugnissoftware/react-spreadsheet-import/blob/master/README.md

Installs the react-spreadsheet-import package using npm. This is the first step to integrate the component into your React project.

```bash
npm i react-spreadsheet-import
```

--------------------------------

### React Spreadsheet Import Component Initialization

Source: https://github.com/ugnissoftware/react-spreadsheet-import/blob/master/README.md

Example demonstrating how to initialize the React Spreadsheet Import component with a specific starting state, allowing the import flow to begin from any defined step.

```tsx
import { ReactSpreadsheetImport, StepType } from "react-spreadsheet-import";

<ReactSpreadsheetImport
  initialStepState={{
    type: StepType.matchColumns,
    data: [
      ["Josh", "2"],
      ["Charlie", "3"],
      ["Lena", "50"],
    ],
    headerValues: ["name", "age"],
  }}
/>
```

--------------------------------

### Fields Configuration for Data Collection

Source: https://github.com/ugnissoftware/react-spreadsheet-import/blob/master/README.md

Defines the structure and validation rules for the data fields to be collected. Each field has a label, key, optional alternate matches, field type, example, and validation rules with severity levels.

```APIDOC
fields: Array<Object>
  - Describes the data you are trying to collect.
  Example Field Object:
    label: string
      - Visible in table header and when matching columns.
    key: string
      - The key used for this field when calling onSubmit.
    alternateMatches: Array<string> (Optional)
      - Allows for better automatic column matching.
    fieldType: {
      type: "input" | "checkbox" | "select"
    }
      - Used when editing and validating information.
    example: string (Optional)
      - Used in the first step to provide an example of expected data.
    validations: Array<Object>
      - Can have multiple validations visible in the Validation Step table.
      - Example Validation Object:
        rule: "required" | "unique" | "regex"
          - The validation rule to apply.
        errorMessage: string
          - Message displayed when validation fails.
        level: "info" | "warning" | "error" (Optional, defaults to "error")
          - Severity level of the validation message.
```

--------------------------------

### Basic Usage of ReactSpreadsheetImport Component

Source: https://github.com/ugnissoftware/react-spreadsheet-import/blob/master/README.md

Demonstrates how to import and use the ReactSpreadsheetImport component in a React application. It shows passing essential props like isOpen, onClose, and onSubmit to manage the import flow.

```tsx
import { ReactSpreadsheetImport } from "react-spreadsheet-import";

<ReactSpreadsheetImport isOpen={isOpen} onClose={onClose} onSubmit={onSubmit} fields={fields} />
```

--------------------------------

### Style Specific Components in Each Step

Source: https://github.com/ugnissoftware/react-spreadsheet-import/blob/master/README.md

Target and style individual components, like `UploadStep`, by specifying their configuration within `customTheme.components`. This provides granular control over specific UI elements within different steps of the import process.

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

--------------------------------

### Optional Props for React Spreadsheet Import

Source: https://github.com/ugnissoftware/react-spreadsheet-import/blob/master/README.md

Lists and describes optional configuration properties for the React Spreadsheet Import component, covering aspects like submission with errors, custom translations, theme configuration, file size limits, and header mapping behavior.

```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
  // 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
```

--------------------------------

### Custom Hooks for Data Transformation and Validation

Source: https://github.com/ugnissoftware/react-spreadsheet-import/blob/master/README.md

Explains the use of custom hooks to transform and validate data at different stages of the import process. Includes hooks for upload, header selection, column matching, and specific validation steps (tableHook, rowHook).

```APIDOC
Hooks:
  uploadStepHook: (file) => Promise<File> | File (Optional)
    - Runs only once after uploading the file.
  selectHeaderStepHook: (header) => Promise<Array<string>> | Array<string> (Optional)
    - Runs only once after selecting the header row.
  matchColumnsStepHook: (mapping) => Promise<Mapping> | Mapping (Optional)
    - Runs only once after column matching. Suitable for expensive operations.
  tableHook: (data: Array<Object>, addError: Function) => Promise<Array<Object>> | Array<Object> (Optional)
    - Runs at the start and on any change in the validation step. Operates on all rows. Can change rows dependent on others.
  rowHook: (data: Object, addError: Function) => Promise<Object> | Object (Optional)
    - Runs at the start and on any row change in the validation step. Operates only on changed rows. Fastest hook for validations and transformations.

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

--------------------------------

### Style All Components of Same Type Globally

Source: https://github.com/ugnissoftware/react-spreadsheet-import/blob/master/README.md

Apply consistent styling to all components of the same type, such as Buttons, by defining `baseStyle` and `defaultProps` within the `customTheme.components` object. This ensures uniformity across similar UI elements.

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

--------------------------------

### TypeScript Types for StepState

Source: https://github.com/ugnissoftware/react-spreadsheet-import/blob/master/README.md

Defines the various states a spreadsheet import process can be in, such as uploading, selecting sheets, selecting headers, matching columns, and validating data. Includes the structure for raw data.

```tsx
  initialStepState?: StepState
  
  type StepState =
    | {
        type: StepType.upload
      }
    | {
        type: StepType.selectSheet
        workbook: XLSX.WorkBook
      }
    | {
        type: StepType.selectHeader
        data: RawData[]
      }
    | {
        type: StepType.matchColumns
        data: RawData[]
        headerValues: RawData
      }
    | {
        type: StepType.validateData
        data: any[]
      }

  type RawData = 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
```

--------------------------------

### ReactSpreadsheetImport Component Required Props

Source: https://github.com/ugnissoftware/react-spreadsheet-import/blob/master/README.md

Details the essential props for configuring the ReactSpreadsheetImport component. These include controlling modal visibility, handling closure without submission, and defining the submission callback with processed data.

```APIDOC
ReactSpreadsheetImport:
  isOpen: Boolean
    - Determines if modal is visible.
  onClose: () => void
    - Called when flow is closed without reaching submit.
  onSubmit: (data, file) => void | Promise<any>
    - Called after user completes the flow. Provides data array, where data keys matches your field keys.
```

--------------------------------

### Customize Global Theme Colors

Source: https://github.com/ugnissoftware/react-spreadsheet-import/blob/master/README.md

Override global theme colors for the ReactSpreadsheetImport component by providing a `customTheme` object with a `colors` property. This allows for brand color integration and global style adjustments.

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

--------------------------------

### Change Component Text with Translations

Source: https://github.com/ugnissoftware/react-spreadsheet-import/blob/master/README.md

Customize the text displayed within the ReactSpreadsheetImport component by providing a `translations` object. This allows for internationalization and tailoring UI text to specific needs.

```tsx
<ReactSpreadsheetImport
  translations={{
    uploadStep: {
      title: "Upload Employees",
    },
  }}
/>
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.