> ## Documentation Index
> Fetch the complete documentation index at: https://flatfile.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Common Configuration

> Shared configuration properties used across all Portal SDKs

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

<ParamField path="publishableKey" type="string" required>
  Publishable key accessed via Flatfile dashboard > Developer settings.
</ParamField>

```typescript src/client.js theme={null}
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

<ParamField path="userInfo" type="{ userId: string, name: string, companyId: string, companyName: string }">
  Additional metadata to be passed to the space as it's created
</ParamField>

```typescript src/client.js theme={null}
const flatfileOptions = {
  publishableKey,
  userInfo: {
    userId: "string",
    name: "string",
    companyId: "string",
    companyName: "string",
  },
};
```

### externalActorId

<ParamField path="externalActorId" type="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.
</ParamField>

```typescript src/client.js theme={null}
const flatfileOptions = {
  publishableKey,
  config: {
    externalActorId: "test-1",
  },
};
```

## Look & Feel

### name

<ParamField path="name" type="string" required>
  Name of the space
</ParamField>

```typescript src/client.js theme={null}
const flatfileOptions = {
  name: "MySpace",
  //additional props
};
```

### themeConfig

<ParamField path="themeConfig" type="object">
  Theme values for the Space, sidebar and data table.
</ParamField>

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](/core-concepts/spaces#branding-and-theming).

```typescript src/client.js theme={null}
const theme = {
  root: {
    primaryColor: "red",
  },
  // see theming reference
};

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

### spaceBody

<ParamField path="spaceBody" type="object">
  Pass in space options to configure a new Space. Find all available parameters
  for spaceBody in the [API
  Reference](https://reference.flatfile.com/api-reference/spaces/create).
</ParamField>

```typescript src/client.js theme={null}
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

<ParamField path="sidebarConfig" type="object">
  Sidebar config values to toggle UI elements
</ParamField>

Within the sidebar, you can set the default page, hide or show the sidebar, and
hide or show the data checklist.

<Note>
  If multiple values are provided for defaultPage, it with prioritize in the
  following order: Sheet, Workbook, Document, Checklist.
</Note>

```typescript sidebarConfig theme={null}
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

<ParamField path="document" type="object">
  Document to pass to space
</ParamField>

[Documents](/core-concepts/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.

<CodeGroup>
  ```typescript src/client.js theme={null}
  const mainDocument = {
    title: "Getting Started",
    body:
      "![Shop](https://coconut.show/logo-big.png)\n" +
      "\\\n" +
      "&nbsp;\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
  };
  ```
</CodeGroup>

## Client-Side Server

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

### environmentId

<ParamField path="environmentId" type="string" required>
  Identifier for environment. This is optional with creating a Workbook
  client-side. The key includes environment-specific configurations.
</ParamField>

```typescript src/client.js theme={null}
const flatfileOptions = {
  publishableKey,
  environmentId,
  //additional props
};
```

### workbook

<ParamField path="workbook" type="object">
  Config of the workbook to be created
</ParamField>

```typescript src/client.js theme={null}
const myWorkbook = {
  // see Blueprint
};

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

### listener

<ParamField path="listener" type="Listener">
  Event listener for responding to Events.
</ParamField>

```typescript src/client.js theme={null}
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

<ParamField path="closeSpace" type="operation: string, onClose: (data: any) => void">
  Options for when to close the iframe and a callback function when the session
  is complete.
</ParamField>

```typescript src/client.js theme={null}
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

<ParamField path="displayAsModal" type="boolean" default="true">
  Display Flatfile as a full screen modal or inline on the page.
</ParamField>

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`.

<CodeGroup>
  ```typescript src/client.js theme={null}
  const flatfileOptions = {
    publishableKey,
    displayAsModal: false,
    //additional props
  };
  ```

  ```css public/styles.css theme={null}
  .flatfile_iframe-wrapper {
    min-width: 768px;
    min-height: 600px;
    width: 992px;
    height: 600px;
  }
  ```
</CodeGroup>