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

​
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

<!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",
                spaceId: "us_sp_your_space_id",
                displayAsModal: true
            });
        });
    </script>
</body>
</html>

​
Configuration Options

OptionTypeRequiredDescription
publishableKeystringYesYour publishable key from the Platform Dashboard
spaceIdstringYesID of the Space to load
displayAsModalbooleanNoShow as modal (true) or inline (false). Default: true

​
Alternative: Create New Spaces

To create a new Space each time instead of reusing an existing one:

  1. Remove the spaceId parameter
  2. Add a workbook configuration object
  3. Optionally add listener for custom data processing
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.

​
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/javascript documentation

​
Example Projects

Basic JavaScript Example

Complete working example with HTML and JavaScript