Skip to main content
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;

​
Making API Requests

The publishableKey is designed exclusively for initializing FlatfileProvider. To make API requests, use the accessToken from the useFlatfileInternal hook.
Use useFlatfileInternal to access the accessToken for making authenticated API calls: 
import { useEffect, useState } from "react";
import { useFlatfileInternal } from "@flatfile/react";
import { FlatfileClient } from "@flatfile/api";

function MyComponent() {
  const { accessToken, sessionSpace } = useFlatfileInternal();
  const [data, setData] = useState([]);

  useEffect(() => {
    // Wait for the space to be created and token to be available
    if (!accessToken || !sessionSpace?.id) return;

    // Initialize the API client with the accessToken
    const api = new FlatfileClient({ token: accessToken });

    const fetchData = async () => {
      try {
        const workbooks = await api.workbooks.list({ 
          spaceId: sessionSpace.id 
        });
        setData(workbooks.data);
      } catch (error) {
        console.error("API Error:", error);
      }
    };

    fetchData();
  }, [accessToken, sessionSpace?.id]);

  return <div>{data.length} workbooks found</div>;
}
For a complete guide on authentication and making API requests, see the React Authentication Guide.

​
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

React Authentication

Using accessToken for secure API requests

Advanced Configuration

Authentication, theming, and advanced options

Server Setup

Backend integration and event handling

​
Example Projects

React Example

Complete React application with Flatfile embedding