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:
- 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>
);
}
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
Quick Links
Example Projects