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({
      spaceId: "us_sp_your_space_id"
    });
  };

  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
  • spaceId: Create a Space in the dashboard, copy the ID from the URL

​
Complete Example

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

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

  const handleImport = () => {
    openPortal({
      spaceId: "us_sp_your_space_id"
    });
  };

  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

​
FlatfileProvider Props

PropTypeRequiredDescription
publishableKeystringYesYour publishable key from the Platform Dashboard
childrenReactNodeYesYour app components

​
openPortal Options

OptionTypeRequiredDescription
spaceIdstringYesID of the Space to load
displayAsModalbooleanNoShow as modal (true) or inline (false). Default: true

​
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">
      <Space 
        spaceId="us_sp_your_space_id"
        displayAsModal={true}
      />
    </FlatfileProvider>
  );
}

​
Alternative: Create New Spaces

To create a new Space each time instead of reusing an existing one, use the Sheet component:

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

const workbookConfig = {
  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">
      <Sheet config={workbookConfig} />
    </FlatfileProvider>
  );
}

For detailed workbook configuration, see the Workbook API Reference.

​
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({
      spaceId: "us_sp_your_space_id"
    });
  };

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

​
Next Steps

  • Styling: Customize the embedded experience in your Platform Dashboard Space settings
  • Data Processing: Set up Listeners in your Space for custom data transformations
  • API Integration: Use Flatfile API to retrieve processed data
  • Advanced Configuration: See @flatfile/react documentation

​
Example Projects

React Example

Complete React application with Flatfile embedding