Quickstart

The DevXP engineering team hosts office hours every Thursday at 11 a.m. Pacific Time where we answer your questions live and help you get up and running with Flatfile. Join us!

For synchronous data import/exchange completed in one session, create a new Space each time Flatfile is opened. This suits situations where a clean slate for every interaction is preferred.

Before you begin

Get your keys

To complete this tutorial, you'll need to retrieve your Publishable key from your development environment.

Note: The Publishable Key is safe to be used in client-side applications as it has limited access to the Flatfile API.

Prepare your React project

Create your file structure

Set up your app to look something like this: Setup your app to look something like this:

├── public/
   └── index.html
├── src/
   └── blueprint.js
   └── index.jsx
├── package.json

In this file structure, your app should have two main directories, public and src. The public directory contains the index.html file, which is the entry point of the application’s front-end. The src directory contains the main components and logic of the application, including the blueprint.js file, which defines the shape of your data, and index.jsx from which your application is run. The package.json file contains the dependencies and scripts for your application.

Build your importer

1. Set up Flatfile

Initialize Flatfile to open in a modal. Pass in your publishableKey from the Flatfile dashboard (here’s a link to the exact spot) to the FlatfileProvider and a new Space will be created on each page load. Paste your key (it should look like pk_123456) where undefined is in the index.jsx file for the const PUBLISHABLE_KEY and you’ll be in good shape. Here are all the files you need to get started, we’ll make edits to these in the next steps.

import ReactDOM from "react-dom/client";
import { useFlatfile, FlatfileProvider, Sheet } from "@flatfile/react";
import { blueprint } from "./blueprint";

// We need to get this from the Flatfile dashboard https://platform.flatfile.com
const PUBLISHABLE_KEY = undefined;

const FlatfilePortal = () => {
  const { openPortal } = useFlatfile();

  return (
    <>
      <button onClick={openPortal}>Open Portal!</button>
      <Sheet config={blueprint} />
    </>
  );
};

const App = () => (
  <FlatfileProvider publishableKey={PUBLISHABLE_KEY}>
    <FlatfilePortal />
  </FlatfileProvider>
);

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<App />);

export const blueprint = {
  name: "Contacts",
  slug: "contacts",
  fields: [
    {
      key: "firstName",
      type: "string",
      label: "First Name",
    },
    {
      key: "lastName",
      type: "string",
      label: "Last Name",
    },
    {
      key: "email",
      type: "string",
      label: "Email",
    },
  ],
};

<!DOCTYPE html>
<html lang="en">
  <head>
    <link rel="stylesheet" type="text/css" href="./styles.css" />
    <!-- react-scripts is going to package your .jsx file and drop it in here as a .js file -->
  </head>
  <body>
    <section id="root"></section>
  </body>
</html>

{
  "name": "example-flatfile-react-app",
  "version": "1.0.0",
  "private": true,
  "dependencies": {
    "@flatfile/react": "^7.9.2",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-scripts": "5.0.1",
    "web-vitals": "^2.1.4"
  },
  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  },
  "browserslist": {
    "production": [">0.2%", "not dead", "not op_mini all"],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  }
}

2. Build and run your React app

Build your React project and start the development server:

  npm install
  npm start

Your browser should automatically open, displaying the Flatfile importer on page load.

3. Build on the Workbook Blueprint

Now, let’s build a Workbook inside the Space for next time.

Update your blueprint.js with this simple Blueprint.
Update index.html to import the Workbook.

When you opened Flatfile, you’ll see a Workbook called “Contacts” that has one Sheet with three fields. You can modify that however you like according to our Blueprint outlined here, but as a simple example, we added one more field here for the Contacts’ Favorite Color.

export const blueprint = {
  "name": "Contacts",
  "slug": "contacts",
  "fields": [
    {
      "key": "firstName",
      "type": "string",
      "label": "First Name"
    },
    {
      "key": "lastName",
      "type": "string",
      "label": "Last Name"
    },
    {
      "key": "email",
      "type": "string",
      "label": "Email"
    },
    {
      "key": "favorite-color",
      "type": "string",
      "label": "Favorite Color"
    }
  ]
}

4. Export your data with an `onSubmit()` action.

Finally, let’s get the data out of our system and to your destination with onSubmit. Once you add this code, when the submit button is clicked, this will be the place you can egress your data. Learn more about Egress Out. Once you have your data, you can do whatever you want with it - from this step you can make another API call to send it where you want. Keep in mind, this is just a simple example. You can do much more with your data and Flatfile! We paginate the data in this call so if you have more than 10,000 records worth of data you’ll need to handle that. We have lots of ideas on how to handle that, if you’d like to learn more.

import ReactDOM from "react-dom/client";
import { useFlatfile, FlatfileProvider, Sheet } from "@flatfile/react";
import { blueprint } from "./blueprint";

const PUBLISHABLE_KEY = undefined;

const FlatfilePortal = () => {
  const { openPortal } = useFlatfile();
  return (
    <>
      <button onClick={openPortal}>Open Portal!</button>
      <Sheet
        config={blueprint}
        onSubmit={async ({ sheet }) => {
          const data = await sheet.allData();
          console.log("onSubmit", data);
        }}
      />
    </>
  ); 
};

const App = () => (
  <FlatfileProvider publishableKey={PUBLISHABLE_KEY}>
    <FlatfilePortal />
  </FlatfileProvider>
); 

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<App />);

5. Transform Data with an `onRecordHook`

Next, we’ll listen for data changes and respond onRecordHook, Once you add this code, when a change occurs, we’ll log the entered first name and update the last name to “Rock.” You’ll immediately see this begin to work when you add or update any records. Learn more about Handling Data

src/index.jsx

import ReactDOM from "react-dom/client";
import { useFlatfile, FlatfileProvider, Sheet } from "@flatfile/react";
import { blueprint } from "./blueprint";
const PUBLISHABLE_KEY = undefined;

const FlatfilePortal = () => {
  const { openPortal } = useFlatfile();
  return (
    <>
      <button onClick={openPortal}>Open Portal!</button>
      <Sheet
        config={blueprint}
        onSubmit={async ({ sheet }) => {
          const data = await sheet.allData();
          console.log("onSubmit", data);

        }}
        onRecordHook={(record) => {
          record.set("lastName", "Rock");
          // If you added a favorite-color field, you can use it here.
          // record.set("favorite-color", "blue");
          return record;
        }}
      />
    </>
  );
};

const App = () => (
  <FlatfileProvider publishableKey={PUBLISHABLE_KEY}>
    <FlatfilePortal />
  </FlatfileProvider>
);

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<App />);

6. Match your brand

By attaching a theme, we will now override colors in your Space to match your brand. See all of the options here in the Theming Reference. The Space component can take a number of options to configure and style the component in the Portal instance. In this case, we’re adding theme to the metadata object and giving the Space a namespace of portal.

src/index.jsx

import ReactDOM from "react-dom/client";
import { useFlatfile, FlatfileProvider, Sheet, Space } from "@flatfile/react";
import { blueprint } from "./blueprint";
const PUBLISHABLE_KEY = undefined;

const FlatfilePortal = () => {
  const { openPortal } = useFlatfile();
  return (
    <Space
      config={{
        namespace: "portal",
        metadata: {
          theme: {
            root: {
              primaryColor: "red",
              textColor: "white",
            },
            sidebar: {
              logo: "https://images.ctfassets.net/hjneo4qi4goj/gL6Blz3kTPdZXWknuIDVx/7bb7c73d93b111ed542d2ed426b42fd5/flatfile.svg",
            },
          },
        },
      }}
    >
      <button onClick={openPortal}>Open Portal!</button>
      <Sheet
        config={blueprint}
        onSubmit={async ({ sheet }) => {
          const data = await sheet.allData();
          console.log("onSubmit", data);
        }}
        onRecordHook={(record) => {
          record.set("lastName", "Rock");
          return record;
        }}
      />
    </Space>
  );
};

const App = () => (
  <FlatfileProvider publishableKey={PUBLISHABLE_KEY}>
    <FlatfilePortal />
  </FlatfileProvider>
);

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<App />);

7. Customize

Continue to customize your importer as needed. For more options, view the full React integration reference.

Example

Explore our React example project for further guidance.

create-flatfile-react-simplified

Clone the simplified Flatfile React tutorial from here.

Documentation

Platform Apps

Orchestration

Automation

Before you begin

Get your keys

Prepare your React project

Create your file structure

Build your importer

1. Set up Flatfile

2. Build and run your React app

3. Build on the Workbook Blueprint

4. Export your data with an `onSubmit()` action.

5. Transform Data with an `onRecordHook`

6. Match your brand

7. Customize

Example

create-flatfile-react-simplified

​Before you begin

​Get your keys

​Prepare your React project

​Create your file structure

​Build your importer

​1. Set up Flatfile

​2. Build and run your React app

​3. Build on the Workbook Blueprint

​4. Export your data with an onSubmit() action.

​5. Transform Data with an onRecordHook

​6. Match your brand

​7. Customize

​Example

create-flatfile-react-simplified

Before you begin

Get your keys

Prepare your React project

Create your file structure

Build your importer

1. Set up Flatfile

2. Build and run your React app

3. Build on the Workbook Blueprint

4. Export your data with an `onSubmit()` action.

5. Transform Data with an `onRecordHook`

6. Match your brand

7. Customize

Example