Theme your Space

Learn how to customize the look and feel of Flatfile to match your brand.

The DevXP engineering team hosts office hours every Thursday at 11 a.m. Pacific Time where we answer your questions live and help you get up and running with Flatfile. Join us!

Flatfile supports modifying most UI elements including colors, fonts, borders, padding, and more via the Space endpoint.

1. Start by simply updating theme.root.primaryColor and theme.sidebar.logo when calling spaces.update().
2. If needed, you can customize the theme further with additional css variables.

---

Building a theme

Learn how to create a Space with a theme, and update a theme from an Event listener.

listener.js

import api from "@flatfile/api";

export default function flatfileEventListener(listener) {
  //listen for space:configure job and build out space
  listener.filter({ job: "space:configure" }, (configure) => {});

  //theme during creation or update your space after it is created
  listener.on("space:created", async ({ context: { spaceId } }) => {
    const updateSpace = await api.spaces.update(spaceId, {
      metadata: {
        theme: {
          root: {
            primaryColor: "red",
          },
          sidebar: {
            logo: "https://image.png",
          },
          // See reference for all possible variables
        },
      },
    });
  });
}

// See full code example (https://github.com/FlatFilers/flatfile-docs-kitchen-sink/blob/main/javascript/theming/index.js)

import { FlatfileListener, FlatfileEvent } from "@flatfile/listener";
import api from "@flatfile/api";

export default function flatfileEventListener(listener: FlatfileListener) {
  //configure space initially
  listener.on(
    "job:ready",
    { job: "space:configure" },
    async ({ context: { spaceId, jobId } }: FlatfileEvent) => {
      await api.jobs.ack(jobId, {
        info: "Gettin started.",
        progress: 10,
      });

      await api.workbooks.create({
        spaceId,
        name: "All Data",
        labels: ["pinned"],
        sheets: [
          {
            name: "Contacts",
            slug: "contacts",
            fields: [
              {
                key: "firstName",
                type: "string",
                label: "First Name",
              },
              {
                key: "lastName",
                type: "string",
                label: "Last Name",
              },
              {
                key: "email",
                type: "string",
                label: "Email",
              },
            ],
            actions: [
              {
                operation: "duplicate",
                mode: "background",
                label: "Duplicate Sheet",
                type: "string",
                description: "Duplicate this Sheet and lock down the original.",
                primary: true,
              },
            ],
          },
        ],
        actions: [
          {
            operation: "submitActionFg",
            mode: "foreground",
            label: "Submit foreground",
            type: "string",
            description: "Submit data to webhook.site",
            primary: true,
          },
        ],
      });

      await api.jobs.complete(jobId, {
        outcome: {
          message: "This job is now complete.",
        },
      });
    }
  );

  //update space after created
  //you can also do this during configuration
  listener.on(
    "space:created",
    async ({ context: { spaceId } }: FlatfileEvent) => {
      //const updateSpace = await flatfile.spaces.update(spaceId, {});

      const updateSpace = await api.spaces.update(spaceId, {
        metadata: {
          theme: {
            root: {
              primaryColor: "red",
            },
            sidebar: {
              logo: "https://image.png",
            },
            // See reference for all possible variables
          },
        },
      });
    }
  );
}

// See full code example (https://github.com/FlatFilers/flatfile-docs-kitchen-sink/blob/main/theming/index.ts)

See full code example in our flatfile-docs-kitchen-sink Github repo

---

Theme reference

theme.root

The sidebar, table and document will automatically inherit theming from your root variables!

Font

fontFamily · string

The font family used throughout the application. Only system fonts are supported at the moment

Colors

primaryColor · string

The primary color used throughout the application.

dangerColor · string

The color used for error messages.

warningColor · string

The color used for warning messages.

successColor · string

The color used for successful Actions.

actionColor · string

The color used for Action buttons and text. This will default to a slightly lighter shade of your primary color.

For a more cohesive aesthetic, use the same color for your Action and Primary color.

borderColor · string

The color used for borders throughout the application.

Buttons

buttonBorderRadius · string

The border radius for all standard buttons.

Badges

badgeBorderColor · string

The border color for all badges.

badgeBorderRadius · string

The border radius for all badges.

Checkboxes

checkboxBorderColor · string

The border color for all checkboxes.

checkboxBorderRadius · string

The border radius for all checkboxes.

Dropdowns, Text Inputs, and Context Menus

interactiveBorderColor · string

The border color for all dropdowns, text inputs, and context menus.

interactiveBorderRadius · string

The border radius for all dropdowns, text inputs, and context menus.

Tabstrip

tabstripActiveColor · string

The color for active tabs in a tabstrip.

tabstripInactiveColor · string

The color for inactive tabs in a tabstrip.

tabstripHoverTextColor · string

The text color for tabs in a tabstrip on hover.

tabstripHoverBorderColor · string

The border color for tabs in a tabstrip on hover.

Modals

modalBorderRadius · string

The border radius for modals.

Pills

pillBorderRadius · string

The border radius for all pills.

Popovers

popoverBackgroundColor · string

The background color for popovers.

popoverBorderRadius · string

The border radius for popovers.

Tooltips

tooltipBackgroundColor · string

The background color for tooltips.

theme.sidebar

You can override the default colors of the sidebar below. If these are not set they will inherit from your root colors.

logo · string

The img path for the logo displayed in the sidebar.

textColor · string

The color of the text in the sidebar.

titleColor · string

The color of the title in the sidebar.

focusBgColor · string

The background color of the active navigation link. The hover state will use the same color with 30% opacity applied.

focusTextColor · string

The text color of the active/focused navigation link.

backgroundColor · string

The background color of the sidebar.

footerTextColor · string

The text color of the footer in the sidebar.

borderColor · string

The color of horizontal lines between sections in the navigation.

theme.document

borderColor · string

The color of horizontal rules in Documents.

theme.table

You can override the default colors and values for different elements in the table below. If these are not set they will inherit from your root values.

Font

fontFamily · string

The font family used throughout the table. Only system fonts are supported at the moment

Active cell

theme.table.cell

cell.active.borderWidth · string

The width of the border around the active cell.

cell.active.borderShadow · string

The box shadow around the active cell.

Column header

theme.table.column

column.header.backgroundColor · string

The background color of the column headers in the table.

column.header.color · string

The text color of the column headers in the table.

Index column

theme.table.indexColumn

indexColumn.backgroundColor · string

The background color of the first column in the table.

indexColumn.color · string

The text color of the first column in the table.

indexColumn.selected.backgroundColor · string

The background color of the first column in the table when selected.

Checkboxes

theme.table.inputs

inputs.checkbox.color · string

The color of the checkboxes in the table.

inputs.checkbox.borderColor · string

The color of the border for the checkboxes in the table.

Filters

theme.table.filters

filters.outerBorderRadius · string

The border radius of the table filters

filters.innerBorderRadius · string

The border radius for the individual filters

filters.outerBorder · string

The border of the table filters. By default there is no border.

When nested objects share the same border radius, small gaps may appear. To resolve this, adjust the inner and outer border radius on the filters to seamlessly fill any gaps.

Buttons

theme.table.buttons

buttons.iconColor · string

The color of the icon buttons in the toolbar and table

buttons.pill.color · string

The color of the pill buttons in the toolbar

filters.pill.backgroundColor · string

The background color of the pill buttons in the toolbar

theme.email

You can theme the guest invite emails as well as guest email verification emails via the properties below. These are sent to a guest when they are invited to a Space via the guest management page in your Space.

Email theming is only available on the pro and enterprise plans.

logo · string

The URL of the image displayed at the top of the email

textColor · string

The color of the text in the email

titleColor · string

The color of the title in the email

buttonBgColor · string

The background color of the button

buttonTextColor · string

The text color of the button

footerTextColor · string

The text color of the footer text

backgroundColor · string

The background color of the email

Example Project

Find the theming example in the Flatfile GitHub repository.

typescript

Clone the theming example in Typescript

javascript

Clone the theming example in Javascript