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.
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>;
}
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:
- Add a
workbook configuration object. Read more about workbooks here.
- 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>
);
}
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>;
}
- 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
Quick Links
Example Projects
