Skip to main content
​
importIdentifier
string
required
This option identifies the data you are importing. If you have multiple imports in your application (i.e. Customers and Sales), you should specify different import identifiers for each type of import. The title of the importer modal will be “Add importIdentifier” unless you supply the title option.
​
title
string
default:"Add ${importIdentifier}"
Replaces the title of the importer modal. For instance, if we set title to “Enjoy Dromo!” you would see the title appear in the importer like this:
The default for this will display “Add importIdentifier”. For instance, if the importIdentifier is Products, it will say “Add Products”.
​
invalidDataBehavior
"BLOCK_SUBMIT" | "REMOVE_INVALID_ROWS" | "INCLUDE_INVALID_ROWS"
default:"REMOVE_INVALID_ROWS"
This option impacts the user’s experience when invalid data is present. When this is set to "BLOCK_SUBMIT", Dromo will disable the ‘Finish’ button preventing the user from submitting with errors. When this is set to "REMOVE_INVALID_ROWS", Dromo will remove any rows with errors and the user will see a dialog indicating “Discard X rows with issues. Submit the rest.” When this is set to "INCLUDE_INVALID_ROWS", Dromo will submit the records with errors and the user will see “Submit your data anyway (errors may occur).”.
REMOVE_INVALID_ROWSINCLUDE_INVALID_ROWSBLOCK_SUBMIT
​
allowEmptySubmit
boolean
default:"true"
Controls whether the user can complete an import even if 0 rows will be submitted. This can be because there are no rows in the import data, or if invalidDataBehavior is set to REMOVE_INVALID_ROWS and all rows have at least one error.If set to false, the submit import button will be disabled when no rows would be submitted.
​
manualInputDisabled
boolean
default:"false"
Show or hide an input table for the user to manually input data. If this is set to true, then there will only be a file dropzone on the page.
​
manualInputOnly
boolean
default:"false"
Show or hide the file dropzone that appears when the importer is started. If this is set to true, then there will only be a manual input table on the page and the dropzone will be hidden. The manualInputDisabled and manualInputOnly settings cannot both be set to true.
​
backendSyncMode
"FULL_DATA" | "MAPPINGS_ONLY" | "DISABLED"
default:"\"DISABLED\""
The backendSyncMode setting controls whether the upload data is sent to the Dromo server for storage, if only the column mapping is sent, or if all processing is completed in the browser.Setting backendSyncMode to "FULL_DATA" enables several features:
  • Viewing your uploads in the Dromo Dashboard
  • Using webhooks and the Dromo API to retrieve results
  • Using the autoMapHeaders setting
It sends all the data from the upload to the Dromo backend for storage.Setting backendSyncMode to "MAPPINGS_ONLY" enables using the autoMapHeaders setting. In this mode, only the column mapping and unique values from 'select' type fields will be stored in our backend.You can set backendSync to "DISABLED" if you have data privacy requirements, and you don’t need the additional functionality the other modes provide.Dromo uses industry-standard best practices to secure your data on our servers.
​
webhookUrl
string
default:"null"
Requires backendSyncMode = “FULL_DATA”This is a URL that is called upon the completion of a successful upload through Dromo. Note: backendSync needs to be set to true for this to work. For more information on webhooks, see the Webhooks documentation.
​
allowCustomFields
boolean
default:"false"
This settings allows users to create custom fields that are not included in the fields object. If set to true, a user will be able to type in a custom field name during the matching phase. These user-provided field names will be included as keys for the returned results.
​
initialData
{ [key: string]: string }[] | string[][]
default:"null"
This allows you to specify the data being uploaded, bypassing the CSV upload stage.You can supply this data in one of two forms:
  • As an array of objects, where each object represents a row. The object itself is a mapping of the key specified in fields and the value for that field in that row. As an example you could pass in: 
    [  {    name: "Jack",    email_address: "jack@thehill.com",  },  {    name: "Jill",    email_address: "jill@thehill.com",  },];
  • As an array of arrays of strings, where each row is represented by an array, with the fields matching the order specified by fields. For example: 
    [  ["Jack", "jack@thehill.com"],  ["Jill", "jill@thehill.com"],];
    All of the supplied data must be in one form or the other – they cannot be mixed.
​
initialFile
File
default:"null"
The initialFile setting allows you to provide a Web API File object, providing the Dromo importer with the raw data to parse and bypassing the user picking a file to import.The File object can come from a file input within your application, or you can build the file object from any source data using the File constructor. The filename extension of the File object should match the format of the file (e.g. if you are providing an Excel file, the filename should end in “.xlsx”.)
​
maxRecords
number
default:"null"
Specify the maximum number of records that a single file can import. This value does not include the headers of the file.If the number of rows in the file exceed this number, the user will be warned and the excess rows will be dropped.
​
maxFileSize
number
default:"1073741824"
Specifies the maximum file size, in bytes, that can be imported. If the user selects a larger file, they will be shown an error message.The maximum file size must be a positive integer and cannot exceed 1 GiB (the default value).
​
developmentMode
boolean
default:"false"
Set this value to true when testing or in development environments. The importer will show a “development mode” banner and the imports will be flagged as development imports. These imports will not be charged against your account.
​
autoMapHeaders
boolean
default:"false"
Requires backendSyncMode = “MAPPINGS_ONLY” or “FULL_DATA”With this setting on, Dromo will try to automatically map the CSV headers to fields based off of previous uploads with the same importIdentifier. The user can still click back and change the mapping if needed.
​
delimiter
string
default:"null"
Allows you to explicitly define a field delimiter for your file (i.e. |). By default, Dromo will attempt auto-detect the delimiter.
​
templateDownloadFilename
string
default:"null"
If set, Dromo will generate a template CSV file using the fields you have defined on the import. Users will see a download link for this template file on the Upload screen of the Dromo importer. The value of this setting will be used as the filename of the template, plus the .csv extension.
​
browserExcelParsing
boolean
default:"true"
Activates the parsing of Excel files in the end user’s browser. Either this setting or backendSyncMode: "FULL_DATA" must be active to enable Excel file parsing.Defaults to true in SDK version >= 2.0.0
​
passThroughUnmappedColumns
boolean
default:"false"
With this setting enabled, Dromo will include all columns not mapped or added as custom fields in the result payload.The values for each row will be in an object with the key $unmapped. The key for each value will correspond to the column index in the original file.Additionally, the metadata object passed to your resultsCallback will include a rawHeaders array containing the original column headers in order, allowing you to map column indexes to their actual header names.In the example below, we only mapped two columns to firstName and email. The remaining unmapped columns were added to the $unmapped object.
// Example results
[
  {
    "$unmapped": {
      "1": "Phillips",
      "3": "(124) 246-3980",
      "4": "United States",
      "5": "93715",
      "6": "",
      "7": "proposed terms"
    },
    "firstName": "Michael",
    "email": "jason@moxie.xyz"
  },
  {
    "$unmapped": {
      "1": "Kukreja",
      "3": "+1 124 246 3981",
      "4": "Canada",
      "5": "J6R",
      "6": "17-Dec-91",
      "7": "qualifying lead"
    },
    "firstName": "Mohit",
    "email": "info@hub.inc"
  }
]

// metadata.rawHeaders
["Name", "Last Name", "Email", "Phone", "Country", "Zip", "Birthday", "Notes"]
For a complete guide on working with unmapped columns including how to use rawHeaders to convert column indexes to header names, see the Accessing Unmapped Columns guide.
​
uploadStep
object
default:"{}"
Settings for the Upload Step experience
​
helpText
string
default:"null"
If set, the given string will be shown to the user on the Upload Step. This can be used to give the user additional context on what file they should upload.Content can be plain text or HTML.
​
sheetOverride
string
default:"null"
If set, the sheet selection modal will be skipped if a sheet matching the string is found in the workbook.If the uploaded file does not have sheets (e.g. a CSV), or the uploaded file has only one sheet, this setting has no effect.
​
templateDownloadOverrideURL
string
default:"null"
If set, the template download button will download from this URL instead of generating a CSV template from your schema fields.This allows you to provide a custom template file that may include additional formatting, instructions, or example data beyond what can be captured in the basic CSV template.The file will be downloaded with the same filename that would be used for the generated template.
uploadStep: {
  templateDownloadOverrideURL: "https://your-domain.com/custom-template.xlsx"
}

​
matchingStep​

object Default: {} Settings for the Matching Step experience
​
matchToSchema
boolean
default:"false"
Added in v2By default, the user is asked to match or ignore all of the column names that exist in their file. If set to true, the user will instead be asked to match only the fields contained in the schema. This is particularly useful when a file may contain numerous irrelevant columns.
​
fuzzyMatchHeaders
boolean
default:"true"
Determines whether Dromo will use fuzzy matching to suggest column mappings during the matching step. If set to false, Dromo will only suggest columns whose headers exactly match a field’s label, key, or alternateMatches.
​
helpText
string
default:"null"
If set, the given string will be shown to the user on the Matching Step. This can be used to give the user additional context on how to match the columns for your import.Content can be plain text or HTML.
​
headerRowOverride
number
default:"null"
If set, matchingStep.headerRowOverride will preset the header row to the 0-indexed row specified. If the header row is after the first row (i.e. headerRowOverride is set to a value greater than 0), rows before the header row will be discarded.
​
suggestCustomFirst
boolean
default:"false"
If set to true, matchingStep.suggestCustomFirst will prioritize the “Add custom field” option by displaying it at the top of the dropdown menu during column matching, rather than positioning it at the end.

​
matchValuesStep​

object Default: {} Settings for the Bulk Fix step experience (formerly known as the Match Values step)
​
helpText
string
default:"null"
If set, the given string will be shown to the user on the Match Values Step. This can be used to give the user additional context on how they should match values with their select fields.Content can be plain text or HTML.
​
maxMappableSelectValues
number
default:"50"
The maximum number of unique values that can be mapped using the Match Values screen per field. If more than maxMappableSelectValues are found in a column of data, Dromo will indicate to the user that there are too many unique values to map on the Match Values screen. The maximum value that can be set for maxMappableSelectValues is 1000.

​
reviewStep​

The settings.reviewStep object contains settings for the Review Step experience. It defaults to {}. The following settings are available:
​
processingText
string
default:"null"
If set, the given string will be shown to the user while the hooks are running at the beginning of the review step. This can be used to give the user additional context if you have any slow-running hooks.
​
helpText
string
default:"null"
If set, the given string will be shown to the user on the Review Step. This can be used to give the user additional context on what issues they should resolve on this step.Content can be plain text or HTML.
​
allowAddingRows
boolean
default:"true"
If false, Dromo will prevent the user from adding any new rows to the data.
Dromo will disable manual input mode (user starts with an empty data table and adds data line by line instead of a file) if this setting is false. Manual input mode specifically requires adding rows.
​
allowRemovingRows
boolean
default:"true"
If false, Dromo will prevent the user from removing any rows from the data.
​
enableUserTransformations
boolean
default:"false"
If true, the ‘Transform data’ feature will be available on the review step.
See the Transform data guide for more information.
​
highlightAutoFixes
boolean
default:"false"
If true, Dromo will highlight any cell that had substantive changes made by automatic transformations, such as:
  • Rounded number values
  • Modified datetime values
  • Select values changed from alternate matches
  • Left-padded zip codes or removed last 4 digits
  • Modified URLs
  • Adjusted phone numbers
    This feature can help users quickly identify and verify automatic transformations made to their data during the import process.
​
locale
string
default:"en"
The language to display within the Dromo importer. Dromo supports the following internationalization (i18n) options:
⌘I