Embed Flatfile directly into any web application using our JavaScript SDK. This approach works with any framework or vanilla JavaScript setup.

Installation

Add the Flatfile JavaScript SDK to your page:

<script src="https://unpkg.com/@flatfile/javascript/dist/index.js"></script>

Or install via npm:

npm install @flatfile/javascript

Basic Implementation

1. HTML Structure

Create a button to trigger the Flatfile embed:

<!DOCTYPE html>
<html>
  <head>
    <title>Data Import</title>
    <script src="https://unpkg.com/@flatfile/javascript/dist/index.js"></script>
  </head>
  <body>
    <button id="import-btn">Import Data</button>

    <script>
      // Implementation goes here
    </script>
  </body>
</html>

2. Initialize Flatfile

document.getElementById("import-btn").addEventListener("click", function () {
  window.FlatFileJavaScript.startFlatfile({});
});

3. Get Your Credentials

publishableKey: Get from Platform Dashboard → Developer Settings

document.getElementById("import-btn").addEventListener("click", function () {
  window.FlatFileJavaScript.startFlatfile({
    publishableKey: "pk_your_publishable_key",
  });
});

For detailed authentication and security guidance, 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.

<!DOCTYPE html>
<html>
  <head>
    <title>Data Import</title>
    <script src="https://unpkg.com/@flatfile/javascript/dist/index.js"></script>
  </head>
  <body>
    <h1>Welcome to our app</h1>
    <button id="import-btn">Import Data</button>

    <script>
      document
        .getElementById("import-btn")
        .addEventListener("click", function () {
          window.FlatFileJavaScript.startFlatfile({
            publishableKey: "pk_your_publishable_key",
            displayAsModal: true,
          });
        });
    </script>
  </body>
</html>

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

You can also deploy and create your workbook via a server-side listener as shown in the above link, rather than passing it in as a client-side property.

window.FlatFileJavaScript.startFlatfile({
  publishableKey: "pk_your_publishable_key",
  workbook: {
    name: "My Import",
    sheets: [
      {
        name: "Contacts",
        slug: "contacts",
        fields: [
          { key: "name", type: "string", label: "Name" },
          { key: "email", type: "string", label: "Email" },
        ],
      },
    ],
  },
});

For detailed workbook configuration, see the Workbook API Reference.

Configuration Options

For complete configuration options including user identity, theming, and advanced features, see Advanced Configuration.

Reusing Existing Spaces

To reuse an existing space, you need to set up a server-side component that retrieves the space access token. The basic client-side approach shown above only works for initial space creation.

For space reuse, you’ll need:

  1. Server-side setup: Use your secret key to retrieve the space and its access token
  2. Client-side update: Use the access token instead of just the publishable key
// Client-side: Get space data from your server
const spaceData = await fetch("/api/spaces/us_sp_your_space_id").then((r) =>
  r.json()
);

// Use the space with access token
window.FlatFileJavaScript.startFlatfile({
  space: {
    id: spaceData.id,
    accessToken: spaceData.accessToken, // Retrieved from server
  },
});

For complete server-side implementation, see Server Setup.

Next Steps

  • Advanced Configuration: See Advanced Configuration for complete options reference
  • Server Setup: Set up Server Setup for space reuse functionality
  • 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

Example Projects