Skip to main content

Settings

Settings are supplied as an object to the Dromo instance on initialization. For details on how to supply settings to Dromo, see the Getting Started guide for the SDK you are using.

importIdentifier

Required
string

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:

note

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

allowInvalidSubmit

Deprecated
boolean
Default: false
Deprecated

allowInvalidSubmit is deprecated in favor of the invalidDataBehavior setting.

allowInvalidSubmit = false is equivalent to invalidDataBehavior = "REMOVE_INVALID_ROWS".

allowInvalidSubmit = true is equivalent to invalidDataBehavior = "INCLUDE_INVALID_ROWS".

This option impacts the messaging on the final screen before submitting data. When this is set to false, Dromo will discard the records with errors and the user will see "Discard X rows with issues. Submit the rest." When this is set to true, Dromo will submit the records with errors and the user will see "Submit your data anyway (errors may occur).":

allowInvalidSubmit = falseallowInvalidSubmit = true

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.

displayEncoding

Removed in v2
boolean
Default: true

Allows the user to specify an encoding for any files they upload. Dromo will default to the encoding that it detects. If displayEncoding is set to true (default), the encoding dropdown is visible in the importer:

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.

backendSync

Deprecated
boolean
Default: false
Deprecated

backendSync is deprecated in favor of backendSyncMode

backendSync = false is equivalent to backendSyncMode = "DISABLED"

backendSync = true is equivalent to backendSyncMode = "FULL_DATA"

The backendSync setting controls whether your data is processed by the Dromo server, or if it is processed entirely in the browser.

Turning on backendSync enables several features:

  • Importing Excel (XLS, XLSX) and XML files
  • Using the autoMapHeaders setting
  • Using webhooks and the Dromo API to retrieve results
  • Viewing your uploads in the Dromo Dashboard

Dromo uses industry-standard best practices to secure your data on our servers. However, you can leave backendSync disabled if you have data privacy requirements, and you don't need the additional functionality backendSync provides. We also offer on-premise installation of Dromo if you have advanced data privacy needs.

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. From more details see Webhooks.

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.

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 on, 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.

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"
}...]

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.

matchingStep

object
Default: {}

Settings for the Matching Step experience

matchToSchema

Added in v2
boolean
Default: false

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

matchValuesStep

object
Default: {}

Settings for the Match Values Step experience

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

object
Default: {}

Settings for the Review Step experience

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.

styleOverrides

object
Default: {}

Specify custom CSS styling on any UI element to make it match your brand requirements.

info

For a visual overlay of the available styling options, see the guide to customizing styles.

global

object
Default: {}

Style overrides that affect the general UI of the Dromo Uploader

  • primaryTextColorstring

    The primary text color

  • secondaryTextColorstring

    The secondary text color

  • customFontURLstring

    A URL to a custom font file

  • customFontFamilystring

    The name of the font family provided by the custom font file

  • backgroundColorstring
    Added in v2
    Default: #ffffff

    The background color of the modal

  • borderRadiusstring
    Added in v2
    Default: 8px

    The border radius of the modal

  • borderStylestring
    Added in v2
    Default: none

    The border style of the modal

  • borderWidthstring
    Added in v2

    The border width of the modal

  • borderColorstring
    Added in v2

    The border color of the modal

primaryButton

object
Default: {}

Style overrides for the primary action button

  • borderRadiusstring

    The radius of the button

  • backgroundColorstring

    The background color of the button

  • textColorstring

    The color of the text in the button

  • borderstring

    The border shorthand property to apply to the button

  • hoverBackgroundColorstring

    The background color of the button while hovering

  • hoverTextColorstring

    The text color of the button while hovering

  • hoverBorderstring

    The border shorthand property to apply to the button while hovering

secondaryButton

object
Default: {}

Style overrides for the secondary action button

  • borderRadiusstring

    The radius of the button

  • backgroundColorstring

    The background color of the button

  • textColorstring

    The color of the text in the button

  • borderstring

    The border shorthand property to apply to the button

  • hoverBackgroundColorstring

    The background color of the button while hovering

  • hoverTextColorstring

    The text color of the button while hovering

  • hoverBorderstring

    The border shorthand property to apply to the button while hovering

dropzone

object
Default: {}

Style overrides for the file dropzone on the upload screen

  • borderWidthnumber
    Default: 2

    The width of the dropzone border in pixels

  • borderRadiusnumber
    Default: 8

    The radius of the dropzone border in pixels

  • borderColorstring

    The color of the dropzone border

  • borderStylestring
    Default: dashed

    The style of the dropzone border

  • backgroundColorstring

    The background color of the dropzone

  • outlinestring

    The outline property of the dropzone

helpText

object
Default: {}

Style overrides for the help text boxes

  • textColorstring

    The text color of the help text

  • backgroundColorstring

    The background color of the help text box

stepperBar

object
Default: {}

Style overrides for the progress bar in the header

  • completeColorstring

    The color of completed steps

  • incompleteColorstring

    The color of steps that have not been started yet

  • currentColorstring

    The color of the step currently in progress

  • fontSizestring
    Added in v2
    Default: 1rem

    The font size of the step text

  • completeFontWeightstring
    Added in v2
    Default: bold

    The font weight of completed steps

  • incompleteFontWeightstring
    Added in v2
    Default: normal

    The font weight of incomplete steps

  • currentFontWeightstring
    Added in v2
    Default: bold

    The font weight of the current step

  • backgroundColorstring
    Added in v2

    The background color of the stepper bar

  • borderBottomstring
    Added in v2

    The bottom border separating the stepper bar from the rest of the modal

locale

string
Default: en

The language to display within the Dromo importer. Dromo supports the following internationalization (i18n) options:

  • bn (Bengali)
  • cs (Czech)
  • da (Danish)
  • de (German)
  • el (Greek)
  • en (English)
  • es (Spanish)
  • fi (Finnish)
  • fr (French)
  • hi (Hindi)
  • hr (Croatian)
  • hu (Hungarian)
  • id (Indonesian)
  • is (Icelandic)
  • it (Italian)
  • ja (Japanese)
  • ko (Korean)
  • lt (Lithuanian)
  • lv (Latvian)
  • ms (Malay)
  • nl (Dutch)
  • no (Norwegian)
  • pl (Polish)
  • pt (Portuguese)
  • ro (Romanian)
  • ru (Russian)
  • sw (Swahili)
  • sv (Swedish)
  • th (Thai)
  • tr (Turkish)
  • uk (Ukrainian)
  • vi (Vietnamese)
  • zh_CN (Chinese - Simplified)
  • zh_TW (Chinese - Traditional)