Common

commonly used embedded properties

All wrapper SDKs take the following shared properties. It’s recommended to start with the defaults in the Guides, then come back here to make customizations.

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,
};

Property	Type	Description
defaultPage	{ documentId?: string, workbook?: { workbookId: string, sheetId?: string }, checklist?: boolean }	Landing page upon loading a Space. Defaults to primary Workbook.
showDataChecklist	boolean	Toggle data config for Space. Defaults to false.
showSidebar	boolean	Determines 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.

src/client.js

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.

src/client.js

const flatfileOptions = {
  publishableKey,
  displayAsModal: false,
  //additional props
};

.flatfile_iframe-wrapper {
  min-width: 768px;
  min-height: 600px;
  width: 992px;
  height: 600px;
}