> ## Documentation Index
> Fetch the complete documentation index at: https://flatfileinc-remove-rss-json.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

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

```typescript src/client.js theme={"system"}
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={"system"}
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={"system"}
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={"system"}
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](/learning-center/guides/theming).

```typescript src/client.js theme={"system"}
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={"system"}
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={"system"}
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](/learning-center/guides/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={"system"}
  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={"system"}
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={"system"}
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={"system"}
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={"system"}
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={"system"}
  const flatfileOptions = {
    publishableKey,
    displayAsModal: false,
    //additional props
  };
  ```

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