All Portal SDKs (JavaScript, React, Angular, Vue) share these common configuration properties. These settings control authentication, theming, user identification, and basic Space configuration. It’s recommended to start with the defaults in the SDK-specific guides, then reference this page to customize your implementation.

​
Authenticate

​
publishableKey

​
publishableKey
string
required
Publishable key accessed via Flatfile dashboard > Developer settings.
src/client.js
const flatfileOptions = {
  publishableKey,
  //additional props
};

​
Identify

While setting up embedded Flatfile, you have the option to either establish a fresh Space during each initialization or reuse an existing Space. These properties specifically apply when creating a new Space.

​
userInfo

​
userInfo
{ userId: string, name: string, companyId: string, companyName: string }
Additional metadata to be passed to the space as it’s created
src/client.js
const flatfileOptions = {
  publishableKey,
  userInfo: {
    userId: "string",
    name: "string",
    companyId: "string",
    companyName: "string",
  },
};

​
externalActorId

​
externalActorId
string
An optional unique identifier that enables our embedded users to be associated with a specific actor in flatfile, enabling repeated through the embedded experience.
src/client.js
const flatfileOptions = {
  publishableKey,
  config: {
    externalActorId: "test-1",
  },
};

​
Look & Feel

​
name

​
name
string
required
Name of the space
src/client.js
const flatfileOptions = {
  name: "MySpace",
  //additional props
};

​
themeConfig

​
themeConfig
object
Theme values for the Space, sidebar and data table.
Theme your Space to create a custom look and feel to match your brand using the actual CSS variables referenced in the app. See all options in our Theming Reference.
src/client.js
const theme = {
  root: {
    primaryColor: "red",
  },
  // see theming reference
};

const flatfileOptions = {
  publishableKey,
  themeConfig: theme,
  //additional props
};

​
spaceBody

​
spaceBody
object
Pass in space options to configure a new Space. Find all available parameters for spaceBody in the API Reference.
src/client.js
const flatfileOptions = {
  publishableKey,
  //additional props, see Create Space endpoint for all the full list of properties (https://reference.flatfile.com/api-reference/spaces/create)
  spaceBody: {
    name: "New Space",
    namespace: "Red",
  },
};

​
sidebarConfig

​
sidebarConfig
object
Sidebar config values to toggle UI elements
Within the sidebar, you can set the default page, hide or show the sidebar, and hide or show the data checklist.
If multiple values are provided for defaultPage, it with prioritize in the following order: Sheet, Workbook, Document, Checklist.
sidebarConfig
const mySidebarConfig = {
  showSidebar: false,
  showDataChecklist: false,
  defaultPage: {
    workbook: {
      workbookId: "123",
      sheetId: "123",
    },
  },
};

const flatfileOptions = {
  sidebarConfig: mySidebarConfig,
  publishableKey,
  workbook,
};
PropertyTypeDescription
defaultPage{ documentId?: string, workbook?: { workbookId: string, sheetId?: string }, checklist?: boolean }Landing page upon loading a Space. Defaults to primary Workbook.
showDataChecklistbooleanToggle data config for Space. Defaults to false.
showSidebarbooleanDetermines if a guest can see the sidebar. If the sidebar is hidden and there are multiple Workbooks in your Space, please specify the desired Workbook ID as your defaultPage.

​
document

​
document
object
Document to pass to space
Documents, written in Markdown, provide extra clarification and instructions to users of a Space. Each Document will appear in the sidebar of a Space. Standard syntax is supported. 
const mainDocument = {
  title: "Getting Started",
  body:
    "![Shop](https://coconut.show/logo-big.png)\n" +
    "\\\n" +
    " \n" +
    "\n" +
    "---\n" +
    "\n" +
    "# Welcome to the Surf Shop!\n" +
    "\n" +
    "Please upload your contacts to the Surf Shop using the Files menu on the left.\n",
};

const flatfileOptions = {
  publishableKey,
  document: mainDocument,
  //additional props
};

​
Client-Side Server

These options are available when configuring your Space client-side.

​
environmentId

​
environmentId
string
required
Identifier for environment. This is optional with creating a Workbook client-side. The key includes environment-specific configurations.
src/client.js
const flatfileOptions = {
  publishableKey,
  environmentId,
  //additional props
};

​
workbook

​
workbook
object
Config of the workbook to be created
src/client.js
const myWorkbook = {
  // see Blueprint
};

const flatfileOptions = {
  publishableKey,
  workbook: myWorkbook,
  //additional props
};

​
listener

​
listener
Listener
Event listener for responding to Events.
src/client.js
const myListener = {
  // listener code
};

const flatfileOptions = {
  publishableKey,
  listener: myListener,
  //additional props
};

​
Configuration

These properties allow you to configure how the importer is mounted, displayed, and closed.

​
closeSpace

​
closeSpace
operation: string, onClose: (data: any) => void
Options for when to close the iframe and a callback function when the session is complete.
src/client.js
const flatfileOptions = {
  publishableKey,
  //additional props
  closeSpace: {
    operation: "submit",
    onClose: () => {},
  },
};
This onClose callback function is called when the ‘operation’ defined in the Action is complete and closes the iframe. It can also be used to perform cleanup actions, such as resetting the state of the parent application or updating the UI.

​
displayAsModal

​
displayAsModal
boolean
default:"true"
Display Flatfile as a full screen modal or inline on the page.
Toggling off this property will update the wrapper css to make the iframe fully inline thereby hiding the close button. All of the child divs will no longer include: .flatfile_displayAsModal which removes all the dialog styling. The default width and height of the container can be overriden in style.css. 
const flatfileOptions = {
  publishableKey,
  displayAsModal: false,
  //additional props
};