These advanced configuration options provide fine-grained control over your embedded Flatfile implementation. Use these properties when you need to customize the user experience, override default behaviors, or integrate with on-premises deployments. Most implementations won’t need these advanced options. Start with the Common Configuration and SDK-specific guides first.

​
Reusing Spaces

During the configuration of embedded Flatfile, you have the flexibility to either reuse an existing Space or generate a new one. These properties come into play when you’re working with an already established Space.

​
space

​
space
{id: string, accessToken: string}
required
Using your secret key, you’ll make a request to a server endpoint to retrieve an accessToken.
src/client.js
const flatfileOptions = {
  publishableKey,
  space: { id: string, accessToken: string },
  //additional props
};

​
Overrides

​
mountElement

​
mountElement
string
default:"flatfile_iFrameContainer"
The element Flatfile will mount to. (Will create if it doesn’t already exist.)
src/client.js
const flatfileOptions = {
  publishableKey,
  mountElement: "flatfile_hello",
  //additional props
};

​
loading

​
loading
ReactElement
A default loading state when the Space is loading. Optionally, you can override the default Loading component.
const LoadingComponent = () => <label>Loading data...</label>;

const flatfileOptions = {
  //additional props
  loading: <LoadingComponent />,
};

​
exitTitle

​
exitTitle
string
default:"Close Window"
The title on the dialog that appears when exiting out of Flatfile.
src/client.js
const flatfileOptions = {
  publishableKey,
  exitTitle: "",
  //additional props
};

​
exitText

​
exitText
string
default:"See below"
The text on the dialog that appears when exiting out of Flatfile.Default: “Are you sure you would like to close this window? This will end your current data import session.”
src/client.js
const flatfileOptions = {
  publishableKey,
  exitText: "",
  //additional props
};

​
exitPrimaryButtonText

​
exitPrimaryButtonText
string
default:"Yes, exit"
The text on the dialog primary button that appears when exiting out of Flatfile.
src/client.js
const flatfileOptions = {
  publishableKey,
  exitPrimaryButtonText: "",
  //additional props
};

​
exitSecondaryButtonText

​
exitPrimaryButtonText
string
default:"No, stay"
The text on the dialog secondary button that appears when exiting out of Flatfile.
src/client.js
const flatfileOptions = {
  publishableKey,
  exitSecondaryButtonText: "",
  //additional props
};

​
errorTitle

​
errorTitle
string
default:"Something went wrong"
The title on the dialog that appears when an unexpected error occurs when loading Flatfile. Note: the error dialog will also include error details regarding the error that occurred.
src/client.js
const flatfileOptions = {
  publishableKey,
  errorTitle: "",
  //additional props
};

​
iframe styles

Theming within the Flatfile application is done in an event listener.
The CSS here is for styling how you want things to look outside of the Flatfile iframe, like the exit dialog, the error container, and the dialog wrapper. This css can go in your style.css in your public folder. Remember to use !important to override values.
public/styles.css
:root {
  --ff-primary-color: #4c48ef !important;
  --ff-secondary-color: #616a7d !important;
  --ff-text-color: #090b2b !important;
  --ff-dialog-border-radius: 4px !important;
  --ff-border-radius: 5px !important;
  --ff-bg-fade: rgba(0, 0, 0, 0.2) !important;
}

/* The default mount element */
/* #flatfile_iFrameContainer {
} */

/* A div around the iframe that contains Flatfile */
/* .flatfile_iframe-wrapper {
} */

/* The actual iframe that contains Flatfile */
/* #flatfile_iframe {
} */

/* Begin style overrides for when Flatfile is displayed as a modal */

/* This class gets appended to the flatfile_iframe-wrapper div */
.flatfile_displayAsModal {
  padding: 50px !important;
  width: calc(100% - 100px) !important;
  height: calc(100vh - 100px) !important;
}

.flatfile_iframe-wrapper.flatfile_displayAsModal {
  background: var(--ff-bg-fade);
}

/* The close button in top right to close modal */
/* .flatfile_displayAsModal .flatfile-close-button {
} */

/* The icon for the close button in top right to close modal */
.flatfile_displayAsModal .flatfile-close-button svg {
  fill: var(--ff-secondary-color);
}

/* The actual iframe that contains Flatfile */
.flatfile_displayAsModal #flatfile_iframe {
  border-radius: var(--ff-border-radius);
}

/* Begin style overrides for when you cancel out of the Flatfile modal */

/* The outer container of the modal that opens when you cancel out of Flatfile */
.flatfile_outer-shell {
  background-color: var(--ff-bg-fade);
  border-radius: var(--ff-border-radius);
}

/* The inner container of the modal that opens when you cancel out of Flatfile */
/* .flatfile_inner-shell {
} */

/* The white box inside the modal that opens when you cancel out of Flatfile */
.flatfile_modal {
  border-radius: var(--ff-dialog-border-radius);
}

/* The container for the buttons you see in the close modal */
/* .flatfile_button-group {
} */

/* Style the buttons you see in the close modal */
/* .flatfile_button {
} */

/* The "yes, cancel" button you see in the close modal */
.flatfile_primary {
  border: 1px solid var(--ff-primary-color);
  background-color: var(--ff-primary-color);
  color: #fff;
}

/* The "no, stay" button you see in the close modal */
.flatfile_secondary {
  color: var(--ff-secondary-color);
}

/* The heading text you see in the close modal */
.flatfile_modal-heading {
  color: var(--ff-text-color);
}

/* The description text you see in the close modal */
.flatfile_modal-text {
  color: var(--ff-secondary-color);
}

/* End style overrides for when you cancel out of the Flatfile modal */

/* End style overrides for when Flatfile is displayed as a modal */

/* The container of the error component */
/* .ff_error_container {
}*/

/* The heading text you see in the error component */
/* .ff_error_heading {
}*/

/* The description text you see in the error component */
/* .ff_error_text {
}*/

​
On Premises

For customers hosting on-premises, the following variables apply.

​
apiUrl

​
apiUrl
string
default:"https://platform.flatfile.com/api"
The endpoint used to interact with the Flatfile API
src/client.js
const flatfileOptions = {
  publishableKey,
  apiUrl: "",
  //additional props
};

​
spaceUrl

​
spaceUrl
string
default:"https://platform.flatfile.com/s"
The URL for accessing the Flatfile Spaces API.
src/client.js
const flatfileOptions = {
  publishableKey,
  spaceUrl: "",
  //additional props
};