Simple

publishableKey

string

required

Publishable key accessed via Flatfile dashboard > Developer settings.

src/client.js

const flatfileOptions = {
  publishableKey,
  //additional props
};

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://flatfile.stoplight.io/docs/api/25e20c8ab61c5-create-a-space)
  spaceBody: {
    name: "New Space",
    namespace: "Red",
  },
};

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

sheet[]

Configuring your sheet for Portal is telling us about the data you’re looking to receive and in what format. You can specify things like fields being required or unique so that some of the built-in validation can help expedite your data import. A sheet contains 3 elements, a name, slug and your fields. We go over Fields in detail in our Blueprint guide, but in the below example, you will see that each field has a key, type and label. Some keys also use the constraints property to specify things like a field needing to be required to have a value or be a unique value in the field values. You might also notice in the below example that a field type of enum also using an additional config property where the options in the enum list will be defined. Example sheet:

const sheet = {
  name: 'Contacts',
    slug: 'contacts',
    fields: [
      {
        key: 'name',
        type: 'string',
        label: 'Name',
        constraints: [
          { type: 'required' }
        ]
      },
      {
        key: 'email',
        type: 'string',
        label: 'Email',
        constraints: [
          { type: 'required' },
          { type: 'unique' },
        ]
      },
    {
      key: 'age',
      type: 'number',
      label: 'Age',
    },
    {
      key: 'employmentStatus',
      type: 'boolean',
      label: 'Currently employed?',
    },
    {
      key: 'birthYear',
      type: 'enum',
      label: 'Birth Year',
      config: {
        options: [
          { value: '1999', label: '1999' },
          { value: '2000', label: '2000' },
          // more here
        ]
      }
    }
  ],
}

Now that we’ve built out the sheet above, we can add it to the full example below. Notice that in addition to the above sheet being added into the script tag, we’ve also referenced the sheet in the flatfileOptions. Quick note: The flatfileOptions object does expect to get a sheet object with that name. So you can name your sheet whatever you like, but if your sheet is const mySheet = {} then you will just need your flatfileOptions object to look like sheet: mySheet instead. Adding on to the Full Example:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Your Page Title</title>
    <script src="https://www.unpkg.com/@flatfile/javascript@latest/dist/index.js"></script>
    <script>
      window.openFlatfile = ({ publishableKey }) => {
        const sheet = {
          name: 'Contacts',
            slug: 'contacts',
            fields: [
            {
              key: 'name',
              type: 'string',
              label: 'Name',
              constraints: [
                { type: 'required' }
              ]
            },
            {
              key: 'email',
              type: 'string',
              label: 'Email',
              constraints: [
                { type: 'required' },
                { type: 'unique' },
              ]
            },
            {
              key: 'age',
              type: 'number',
              label: 'Age',
            },
            {
              key: 'employmentStatus',
              type: 'boolean',
              label: 'Currently employed?',
            },
            {
              key: 'birthYear',
              type: 'enum',
              label: 'Birth Year',
              config: {
                options: [
                  { value: '1999', label: '1999' },
                  { value: '2000', label: '2000' },
                  // more here
                ]
              }
            }
          ],
        }
        const flatfileOptions = {
          publishableKey,
          sheet,
          // more to come here in the following sections
        }
        window.FlatFileJavaScript.startFlatfile(flatfileOptions)
      }
    </script>
  </head>
  <body>
    <h3>We are going to import your data now. Click the button below to start your import</h3>
    <div class="container">
      <button
        id="flatfileButton"
        onclick="openFlatfile({ publishableKey: 'YOUR_PUBLISHABLE_KEY'})"
      >
        Import Contacts
      </button>
    </div>
    <br>
  </body>
</html>

onRecordHook()

Now that we have configured our Sheet, we will look at the Data Validations piece. Data Validations in the Portal setup can be written inside of the onRecordHook callback of the flatfileOptions object. This callback will run on each record at initialization and then on any subsequent changes of the data. The callback you write will get the record passed in by default and you can update that record with any updates you’d like to make and return it as the output of the callback and that will update the record in the UI. For the purposes of being super basic in this example, let’s say you like to store the name property in your Database as all uppercase values. To ensure that this happens, we can write a simple function using JavaScript’s toUpperCase method to make sure all values continually get put to all uppercase values.

// taking just the flatfileOptions object out from the full example
const flatfileOptions = {
  publishableKey,
  sheet,
  onRecordHook: (record) => {
    const name = record.get('name')
    if (name) {
      record.set('name', name.toUpperCase())
      record.addInfo('name', 'We updated the values to all uppercase')
    }
    return record
  },
}

What you’ll notice from the above is that we can use a built-in record.get() method with the fields key value to initially get the record’s value. We can then use the record.set() method to set the new value for the field and then we can optionally provide some context onto the record with record.addInfo() to set a message on the field. Quick note on the additional info being added: You can add additional info on a field with several different validation levels. You can use addInfo as a courtesy to let your end use know what transformations is happening with the data, you could use addWarning to provide a warning message (the main difference between the two is how noticeable a field is after running the hook in the UI) and finally, you can use addError which not only highlights everything in red, but changes the data’s validation state to being not valid and making the end use fix the issue. Here’s the above added to the full code snippet:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Your Page Title</title>
    <script src="https://www.unpkg.com/@flatfile/javascript@latest/dist/index.js"></script>
    <script>
      window.openFlatfile = ({ publishableKey }) => {
        const sheet = {
          name: 'Contacts',
          slug: 'contacts',
          fields: [
            {
              key: 'name',
              type: 'string',
              label: 'Name',
              constraints: [
                { type: 'required' }
              ]
            },
            {
              key: 'email',
              type: 'string',
              label: 'Email',
              constraints: [
                { type: 'required' },
                { type: 'unique' },
              ]
            },
            {
              key: 'age',
              type: 'number',
              label: 'Age',
            },
            {
              key: 'employmentStatus',
              type: 'boolean',
              label: 'Currently employed?',
            },
            {
              key: 'birthYear',
              type: 'enum',
              label: 'Birth Year',
              config: {
                options: [
                  { value: '1999', label: '1999' },
                  { value: '2000', label: '2000' },
                  // more here
                ]
              }
            }
          ],
        }
        const flatfileOptions = {
            publishableKey,
            sheet,
            onRecordHook: (record) => {
                const name = record.get('name')
                if (name) {
                  record.set('name', name.toUpperCase())
                  record.addInfo('name', 'We updated the values to all uppercase')
                }
                return record
              },
            // more to come here in the following sections
        }
        window.FlatFileJavaScript.startFlatfile(flatfileOptions)
      }
    </script>
  </head>
  <body>
    <h3>We are going to import your data now. Click the button below to start your import</h3>
    <div class="container">
      <button
          id="flatfileButton"
          onclick="openFlatfile({ publishableKey: 'YOUR_PUBLISHABLE_KEY'})"
      >
        Import Contacts
      </button>
    </div>
    <br>
  </body>
</html>

onSubmit()

Flatfile has many different ways to handle and process data back to you once an import has happened, but the easiest in this context is the built-in onSubmit callback where the data is provided to you. This onSubmit callback passes in an object that has the records for you to send wherever you might need to store them. For example purposes, we are going to simply log the results, but this is where you could send results to your server or pass them back to your application. When the data is finished and available, the onSubmit method will provide you with a sheet that you can use the built-in methods like allData(), validData(), errorData(), inChunks() and stream() to get your data. Here’s a quick reference table for the available methods and what they do.

Method	Example Usage	Return description	Additional notes
`allData()`	`sheet.allData()`	This returns all the data that is being imported.	All of the data does come with a way of determining whether the individual record was valid or not, but it returns all records regardless of validity.
`validData()`	`sheet.validData()`	This returns all records that pass are flagged as being valid and leaves off all invalid records.
`errorData()`	`sheet.errorData()`	This will return only those records that are considered invalid and leaves off any valid records.
`inChunks(cb, {chunkSize: number})`	`sheet.inChunks((data) => // do something with each chunk, { chunkSize: 100 })`	The inChunks method will run the callback function provided on each chunk of data until all chunks have been processed.	The default chunk size is 1000
`stream(cb)`	`sheet.stream((data) => // do something to each chunk of the stream)`	The stream method will run the callback on every 1000 records available until all records have been processed

With all those methods brought to light, let’s simply use the allData method to get all the records at once and then console log them in the process.

// just working within the confines of the flatfileOptions object
const flatfileOptions = {
  publishableKey,
  sheet,
  onRecordHook: (record) => {
    const name = record.get('name')
    if (name) {
      record.set('name', name.toUpperCase())
      record.addInfo('name', 'We updated the values to all uppercase')
    }
    return record
  },
  onSubmit: async ({sheet}) => {
    const data = await sheet.allData()
    console.log(data)
  }
}

Now let’s put it all together in the full example:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Your Page Title</title>
    <script src="https://www.unpkg.com/@flatfile/javascript@latest/dist/index.js"></script>
    <script>
      window.openFlatfile = ({ publishableKey }) => {
        const sheet = {
          name: "Contacts",
          slug: "contacts",
          fields: [
            {
              key: "name",
              type: "string",
              label: "Name",
              constraints: [{ type: "required" }],
            },
            {
              key: "email",
              type: "string",
              label: "Email",
              constraints: [{ type: "required" }, { type: "unique" }],
            },
            {
              key: "age",
              type: "number",
              label: "Age",
            },
            {
              key: "employmentStatus",
              type: "boolean",
              label: "Currently employed?",
            },
            {
              key: "birthYear",
              type: "enum",
              label: "Birth Year",
              config: {
                options: [
                  { value: "1999", label: "1999" },
                  { value: "2000", label: "2000" },
                  // more here
                ],
              },
            },
          ],
        };
        const flatfileOptions = {
          publishableKey,
          sheet,
          onRecordHook: (record) => {
            const name = record.get("name");
            if (name) {
              record.set("name", name.toUpperCase());
              record.addInfo("name", "We updated the values to all uppercase");
            }
            return record;
          },
          onSubmit: async ({ sheet }) => {
            const data = await sheet.allData();
            console.log(data);
          },
        };
        window.FlatFileJavaScript.startFlatfile(flatfileOptions);
      };
    </script>
  </head>
  <body>
    <h3>
      We are going to import your data now. Click the button below to start your
      import
    </h3>
    <div class="container">
      <button
        id="flatfileButton"
        onclick="openFlatfile({ publishableKey: 'YOUR_PUBLISHABLE_KEY'})"
      >
        Import Contacts
      </button>
    </div>
    <br />
  </body>
</html>

The above example is a fully working example that only needs to have your publishable key changed out for it to work as expected. As a quick reminder, this is just the baseline of what Flatfile is capable of doing. You can check out more resources in our documentation here.

Documentation

Platform Apps

Orchestration

Automation

publishableKey

spaceBody

themeConfig

sheet[]

onRecordHook()

onSubmit()

Documentation

Platform Apps

Orchestration

Automation

​publishableKey

​spaceBody

​themeConfig

​sheet[]

​onRecordHook()

​onSubmit()

publishableKey

spaceBody

themeConfig

sheet[]

onRecordHook()

onSubmit()