Embed Flatfile in your React application using our React SDK. This provides React components and hooks for seamless integration.

Installation

npm install @flatfile/react

Basic Implementation

1. Wrap Your App

Wrap your application with the FlatfileProvider:

import { FlatfileProvider } from "@flatfile/react";

function App() {
  return (
    <FlatfileProvider publishableKey="pk_your_publishable_key">
      <YourApp />
    </FlatfileProvider>
  );
}

2. Add Import Trigger

Use the useFlatfile hook to open Flatfile:

import { useFlatfile } from "@flatfile/react";

function YourComponent() {
  const { openPortal } = useFlatfile();

  const handleImport = () => {
    openPortal({});
  };

  return (
    <div>
      <h1>Welcome to our app</h1>
      <button onClick={handleImport}>Import Data</button>
    </div>
  );
}

3. Get Your Credentials

publishableKey: Get from Platform Dashboard → Developer Settings

For authentication guidance including JWT tokens and user management, see Advanced Configuration.

Complete Example

The example below will open an empty space. To create the sheet your users should land on, you’ll want to create a workbook as shown further down this page.

import React from "react";
import { FlatfileProvider, useFlatfile } from "@flatfile/react";

function ImportButton() {
  const { openPortal } = useFlatfile();

  const handleImport = () => {
    openPortal({});
  };

  return <button onClick={handleImport}>Import Data</button>;
}

function App() {
  return (
    <FlatfileProvider publishableKey="pk_your_publishable_key">
      <div>
        <h1>My Application</h1>
        <ImportButton />
      </div>
    </FlatfileProvider>
  );
}

export default App;

Configuration Options

For all configuration options including authentication, theming, and advanced settings, see Advanced Configuration.

Using Space Component

For more control, you can use the Space component directly:

import { FlatfileProvider, Space } from "@flatfile/react";

function App() {
  return (
    <FlatfileProvider
      publishableKey="pk_your_publishable_key"
      config={{ displayAsModal: true }}
    >
      <Space config={{ name: "Embedded Space" }} />
    </FlatfileProvider>
  );
}

Creating New Spaces

To create a new Space each time:

  1. Add a workbook configuration object. Read more about workbooks here.
  2. Optionally deploy a listener for custom data processing. Your listener will contain your validations and transformations
import { FlatfileProvider, Workbook } from "@flatfile/react";

const workbookConfig = {
  name: "My Import",
  sheets: [
    {
      name: "Contacts",
      slug: "contacts",
      fields: [
        { key: "name", type: "string", label: "Name" },
        { key: "email", type: "string", label: "Email" },
      ],
    },
  ],
};

function App() {
  return (
    <FlatfileProvider publishableKey="pk_your_publishable_key">
      <Workbook config={workbookConfig} />
    </FlatfileProvider>
  );
}

For detailed workbook configuration, see the Workbook API Reference.

Reusing Existing Spaces

For production applications, you should create Spaces on your server and pass the Space ID to your React application:

Server-side (Node.js/Express)

// Create Space on your server
const space = await api.spaces.create({
  name: "User Import",
  workbooks: [workbookConfig],
});

// Pass spaceId to your React app
res.json({ spaceId: space.data.id, token: space.data.accessToken });

Client-side (React)

import { FlatfileProvider, useFlatfile } from "@flatfile/react";

function ImportComponent() {
  const { openPortal } = useFlatfile();
  const [spaceId, setSpaceId] = useState(null);

  useEffect(() => {
    // Get Space ID from your server
    fetch("/api/create-space")
      .then((res) => res.json())
      .then((data) => setSpaceId(data.spaceId))
      .then((data) => setToken(data.token));
  }, []);

  <FlatfileProvider accessToken="token">
    <Space id="spaceId">
  </FlatfileProvider>

  const handleImport = () => {
    if (spaceId) {
      openPortal({});
    }
  };

  return <button onClick={handleImport}>Import Data</button>;
}

This approach allows you to:

  • Create Spaces with server-side authentication
  • Add custom event listeners and data processing
  • Control Space lifecycle and cleanup

For complete server setup examples, see Server Setup.

TypeScript Support

The React SDK includes full TypeScript support:

import { FlatfileProvider, useFlatfile } from "@flatfile/react";

interface Props {
  onDataImported?: (data: any) => void;
}

function ImportComponent({ onDataImported }: Props) {
  const { openPortal } = useFlatfile();

  const handleImport = (): void => {
    openPortal({});
  };

  return <button onClick={handleImport}>Import Data</button>;
}

Next Steps

Example Projects