Skip to content
demuddler

Component reference

Reference for importer properties, methods and events. Set the schema, choose the features and handle completed imports.

Import @demuddler/importer to register <demuddler-importer>. You can import it more than once, and it does nothing during server rendering. Install gives a complete first example. Deliver rows describes the result and your backend.

The loader makes the hosted frame when the element connects to the document. When you remove the element, its runtime stops. Give the element a height. Set the configuration before a file opens. Keep the element mounted during delivery.

The examples below use importer for the element:

import "@demuddler/importer";
const importer = document.querySelector("demuddler-importer");
Attribute Property Default and behaviour
licence-key licenceKey The public licence key. The hosted importer needs it.
runtime-url runtimeUrl https://runtime.demuddler.com/version/<version>, with the runtime version that ships in the package. Set another version to pin a runtime version. Any other address throws a TypeError. For development, the loader also accepts the same path over http on localhost, 127.0.0.1 or [::1].
theme theme system. It also accepts light or dark.
density density compact. Use comfortable for more space around controls.
handoff handoff false. Sends the completed import to a handler on your page. Register complete too.
no-file noFile false. With handoff, removes the file download choices. Without handoff, it does nothing.
cancelable cancelable false. Shows the cancel action and sends cancel.
show-full-screen showFullScreen false. Shows the Full screen button after the theme button. A press sends fullscreen.
is-full-screen isFullScreen false. Set it while your page fills the window with the importer. The button then offers to leave full screen.
cancel-label cancelLabel Replaces the text of the cancel control.

A boolean attribute is on when it is present, so handoff="false" still turns on handoff. To turn it off, remove the attribute or set the property to false. When licenceKey or runtimeUrl changes, the frame loads again and the importer loses the open file.

A string attribute cannot hold these values. Use the JavaScript properties or the matching React props. To change a setting, assign a new object. The loader does not see a change to an existing object.

Property Value Purpose
schema ImporterSchema The fields and rules that your page owns. If you omit it, the importer makes a schema from the file. See Schema.
file File, File[] or null Gives browser files to the importer, so the person does not have to drop them. For more control, use open().
messages Messages Your text for the message keys. See Styling.
appearance ImporterAppearance Brand, tokens, icons and custom CSS. See Styling.
features ImporterFeatures Removes the capabilities that you choose. See Features.
fileSettings FileSettings How to read each new file. See File settings.
duplicateScan DuplicateScan The duplicate scan for each read. See Duplicate scan.
validationHooks ValidationHooks Functions on your page that check values for custom rules, by hook name. Only the names go into the frame. See Validation hooks.

Every value except the hook functions must be data that the browser can copy with structured clone. Do not put functions or DOM nodes in them. The validationHooks functions stay on your page.

Property Before loading Meaning
isReady false true after the runtime reports that it is ready.
stats null The latest parse statistics, with the source schema and the row count.
validation null The latest validation report.
licence null The plan that the frame applies: { plan, reason, is_licensed, has_attribution, export_limit }. is_licensed is false when the licence check refused: the importer then opens no file. reason is null when the API gave the plan, unreachable when a stored answer gave it, and the cause of a refusal otherwise. The licence is refused lists each value. export_limit is null when there is no limit.

Use events to react to changes.

Method Return Behaviour
open(file) Promise<void> Opens a File or File[]. Attach the element to the page first. Catch a rejected promise.
reset() void Asks the importer to go back to the opening screen. If a reset is allowed, it frees the current file. Do not use it to cancel a delivery.
recheckValidationHooks() void Sends every value to the validation hooks again, after your own data changed. The importer drops the earlier answers.
notify(message, options) void Shows a text notice. The options are tone, duration and id.

notify shows message as text, never as HTML. The message has 1 to 500 characters. The tones are info, warn, bad and good. A notice closes after duration milliseconds, 5000 by default and at most 600,000. With 0, it stays open until the person closes it. A notice with the same id, of at most 100 characters, replaces the earlier one.

importer.notify("Your import settings were updated.", { tone: "info", duration: 4000 });

Each event is a CustomEvent on the importer element. Events do not bubble, and they do not cross a shadow boundary. Register your listeners on the element.

DOM event detail React callback and argument
ready No payload onReady()
licence The same object as licence, before ready and again when the plan changes No callback. Read licence.
open { files, bytes } onOpen(detail)
parse-progress { bytes, total, rows } onParseProgress(progress)
parse-complete { stats } onStats(stats)
validate { validation } onValidate(validation)
complete { result, waitUntil } onComplete(result). Return the delivery promise.
export { format, rows } onExport(detail)
limit { rows, limit } onLimit(detail)
themechange { theme } onThemeChange(detail)
escape No payload. A person pressed Escape and nothing in the importer used it, for example to leave a full-screen view. onEscape()
fullscreen { isFullScreen }, the state that the person asked for. Fill the window with the importer, or stop, then set isFullScreen. onFullScreen(detail)
cancel No payload onCancel()
error { message, cause } onError(detail)

open.files holds the file names. parse-complete comes after each read of the file, also after a change in File settings or the column menu. stats.schema holds the values for the file warnings, such as formula_cells, ragged_rows, unread_values, filled_merged_ranges, unclosed_quote_line and unreadable_sheets. stats.schema.sheets lists each worksheet with its name, rows, columns and first column names. n_errors counts every problem in the read. stats.elapsedMs is the time of the read in milliseconds.

stats.appended has one entry for each combined file after the first. Each entry has rows_added, missing, extra (dropped columns) and failed_cells. failed_cells counts the values that do not fit the column types of the first file. unread_values does not count them.

export.rows is the number of exported rows. limit.rows is the number of source rows, and limit.limit is your plan limit. After a limit notice, the importer did not deliver the full file. See Choose the rows to deliver.

The importer shows runtime errors itself. Use error if your application must show its own feedback.

The importer does not ignore a value that it cannot use. An unknown key, at any level, is an error, and so is a value outside its range. The importer then keeps the value that it had.

  • The schema, file, theme, density, cancelLabel and validationHooks properties, and notify(), throw a TypeError at once. open() returns a rejected promise with one, and so does the first next() of batches(). The message names the setting and the first problem, for example schema.fields[0].colour is not a known setting.
  • The frame checks the other object properties. A wrong value sends error, with a message of the same form.
  • A wrong attribute sends error, because a browser drops an error that an attribute causes.
  • A message from the frame that the loader cannot read sends error.

If the frame refuses a schema, it shows no data. It shows the runtime.schemaRefused message until it receives a schema that passes. The schema limits are in Limits and refused schemas.

Event payloads and the read-only state can hold file names, column names and example values. Do not send them to analytics, logs or another remote service. See Network requests and data.

The component fills its container and controls its own scrolling. The sheet scrolls, and the page does not. Set its height in your page CSS:

<demuddler-importer style="height: 100dvh"></demuddler-importer>

If nothing gives it a height, the frame gets the default iframe height of 150 pixels, which is too small to use.

The importer has a fixed header, step content and footer. The header has the file name, the three steps and the theme toggle. The footer has the attribution mark on Free, Shortcuts, Cancel and the next step.

Widget Title Where it shows
fixes Fixes A tab of the Fix values sidebar. Every suggested fix, each with a full preview.
problems Problems A tab of the Fix values sidebar. Problem groups and file warnings. A click opens the group and selects its column.
history History A tab of the Fix values sidebar. Changes, with undo and redo.
file-settings File settings Opens from the file name in the header. How the file is read: encoding, separator, header row and sheet.
output Import preview On the Import step. A preview of the rows that your application receives.

The sidebar has one more tab, Repeated rows, which counts the repeated rows.

The importer follows three steps. Match columns lists the columns of the file. For each column, it shows the type that the importer found, two values, the field that the column goes to and the reason for the match. People can change the type there. A person cannot leave Match columns until each required field has a column. Fix values shows the sidebar on the left and the table, with the columns that your schema imports. A column that a split adds also shows, so a person can match it. A problem card offers the exact fixes for its column, which apply at once. Fixes holds every fix, and each one shows a preview before it changes a value. Import shows the rows to import, the rows to leave out, the repeated rows, the file formats and the import preview.

When the frame is narrower than 1,024 pixels, the sidebar opens as a sheet from the button above the table.

features removes the capabilities that your product does not want. The importer removes a capability that is off from every menu, button and shortcut. It does not show as disabled.

importer.features = {
editCells: true,
transforms: true,
excludeRows: true,
themeToggle: true,
fileSettings: true,
downloads: ["csv", "xlsx"],
};
Feature Default When it is false or empty
editCells true People cannot edit, paste into or find and replace cells.
transforms true Removes Transform from the column menu, with its fixes such as Merge columns and Change values. It also removes Replace text, Split column, the suggested fixes and the fix marks in the column headers.
excludeRows true People cannot exclude single rows.
themeToggle true Removes the light and dark control.
fileSettings true Removes File settings from the header, and Type, Date order and Decimal comma from the column menu. People cannot change how the importer reads the file.
downloads ["csv", "xlsx"] The download formats, in order. [] offers no file. Use it with handoff.

If you know how the files of your users are written, set fileSettings. The importer then reads each file correctly the first time:

import type { DuplicateScan, FileSettings } from "@demuddler/importer";
export const fileSettings: FileSettings = {
encoding: "windows-1252",
delimiter: ";",
columns: { "Join date": { dtype: "date", date_order: "dmy" } },
};
export const duplicateScan: DuplicateScan = { keys: ["email"], keep: "last" };
importer.fileSettings = fileSettings;
importer.duplicateScan = duplicateScan;
Key Value
encoding A label from the WHATWG Encoding Standard, such as windows-1252.
delimiter One ASCII character that is not ", such as ; or \t.
quote One ASCII character that is not a space and not the separator.
is_backslash_escaped true when \" is a quotation mark inside a quoted value, as MySQL writes it. CSV only.
has_header false when the first row holds data, not column names.
header_rows Rows that form the header, from 1 to 4. With 2 or more, the rows join into one name for each column, such as Billing · Email.
skip_rows Lines, or sheet rows, to skip above the header, from 0 to 999,999,999.
sheet The worksheet to read. Without it, the importer opens the first sheet with a table, and a workbook with two or more sheets asks the person to choose.
fill_merged_cells false keeps the value of a merged range in its first cell only. true by default. Spreadsheets only.
null_markers Up to 100 extra words for an empty cell, such as TBD, of at most 100 characters each. CSV only.
columns Settings for single columns, by column name: dtype (text, int64, float64, bool or date), date_order (ymd, dmy or mdy) and has_decimal_comma.

The importer detects each setting that you leave out. For example, with { has_header: false } it still detects a ; separator. An unknown key, an unknown encoding label or another value that the importer cannot use refuses the whole setting. See Refused settings.

A change applies to the next file. The importer does not read an open file again. Set fileSettings before file or open(). People see these values in File settings and the column menu, and can change them there, unless features.fileSettings is false.

Set duplicateScan to find repeated rows in each read. Then skipDuplicates works without a scan in the Import step.

  • keys holds column names or field keys, each a string that is not empty. The importer first looks for a column with that name, then for the column mapped to a field with that key. A repeated header gets a number, such as email and email_2, so each name belongs to one column. A row repeats another when every key has the same value. Capital letters from A to Z and spaces around a value do not matter. An empty list compares every column.
  • keep is the copy that stays: first, the default, or last.

The Import step shows this scan, and people can change it. The importer scans while the Import step shows, and again before it delivers or downloads rows, so the scan includes the latest edits. A new file, or a new read of the file, starts again from your scan. A change to duplicateScan applies at once.

A field key has no effect until a column is mapped to it. If a key names no column and no field, the importer runs no scan and sends error. The message uses the finish.unknownKeys message key.

The frame keeps its own styles. CSS and markup from your page do not go into it, and its styles do not come out. You load no stylesheet. In your page CSS, set only the size of demuddler-importer. See Sizing it.

The default theme follows prefers-color-scheme. To choose one mode, set theme="dark" or theme="light".

To make the importer match your product, set appearance:

importer.appearance = {
brand: {
name: "Acme Data",
logoSrc: "data:image/svg+xml;base64,PHN2Zy...",
logoAlt: "Acme Data",
},
tokens: {
fontFamily: '"Acme Sans", sans-serif',
accent: "#075985",
canvas: "#f8fafc",
surface: "#ffffff",
border: "#cbd5e1",
radius: "2px",
gridRowHeight: "32px",
},
icons: {
search: {
viewBox: "0 0 16 16",
paths: ["M11.5 11.5 15 15M7 12A5 5 0 1 1 7 2a5 5 0 0 1 0 10Z"],
},
},
stylesheet: `
[part~="header"] { background: #f1f5f9; }
[part~="widget-problems"] [part~="widget-header"] { background: #fef2f2; }
`,
};

The brand shows before and after a file opens. name is the visible product name, demuddler by default. logoSrc accepts only a PNG, JPEG, WebP, GIF or SVG data image. The importer refuses a web address, because the frame loads no image from another server. The importer draws it as an image, never as markup. If the logo already includes the product name, set showName: false. logoAlt is then the text for the logo, and name is the default.

Tokens apply on every plan. TypeScript lists them in AppearanceTokens:

Group Tokens
Type fontFamily, fontSize, lineHeight, fontWeight, fontWeightStrong
Surfaces canvas, surface, surfaceRaised, panel (the sidebar), gridHeader (the table header and the widget headers)
Text text, textMuted
Lines border, gridLine, borderWidth, borderStyle
States accent, accentText, danger, warning, success, focus, selection (the selected cell and active choices), problemTint (a cell or a count with a problem), disabledOpacity
Shape and size radius, radiusSmall, gridRowHeight, gridHeaderHeight, shadowPopover

An unknown token name, or a token of more than 500 characters, refuses the whole appearance. Each token is one CSS value. It cannot contain { } ; < > \ or a comment, and its brackets and quotes must balance. It cannot load an image with url() or another image function. The importer ignores a token that breaks these rules. If you set accent and not accentText, the text on the accent colour is white. No token changes the attribution mark.

The frame loads no font from your page. fontFamily alone does not download a font. See Styling and external assets.

An icon entry replaces a built-in icon with SVG path data: a viewBox of four numbers and a list of paths. The importer ignores an entry that is not path data. The names include the column type icons (type-text, type-number, type-date, type-bool, type-email), the widget icons (problems, fixes, history, output, file-settings) and more.

stylesheet is the last stylesheet of the component. It applies only on Starter or Pro. Free applies the tokens and ignores stylesheet, because a stylesheet can hide the attribution mark. The stylesheet runs in the frame, beside the values of the file, and it can load images from any HTTPS address. Use only CSS that you control. For the rules on a local host, see Local development.

Part names are the only public styling hooks. Select them with [part~="name"] or ::part(name). Class names and data-slot values are internal and can change in any release. The package exports the fixed names as PART_NAMES. The PartName type adds the widget-<name> and icon-<name> families, and dock-left.

Every widget has part="widget widget-<name>". The sidebar has part="dock dock-left". These are some of the other parts:

Area Parts
Frame header, table, row, cell, footer, drop-area
Scrolling minimap and minimap-thumb (the vertical scrollbar with the problem map), horizontal-scroll
Footer marks attribution, development-badge
Help and view tooltip, viewer-control (the maximise control)
File settings file-settings, file-settings-apply, and in the column menu column-read-type, column-date-order, column-decimal-comma
Fixes cleanup-show-unchanged, column-replace, replace-popover, fix-popover, fix-values
Import step dedupe-menu, dedupe-keys, dedupe-keep, percent-sign
Field picker field-description
Rule editor rules-sheet, rule, rule-save, rule-remove, rule-values, pattern-preview. It opens from column-rules in the column menu.
File warnings file-warnings (the list in Problems), file-warning (one warning)

Every visible message has a key in the Messages type. Give only the keys that you want to replace. A key that you omit keeps the built-in English text. The file warnings use the fileWarnings.* keys. The Development badge always shows its built-in text, and licence.development cannot change it.

Two importers share nothing. Each has its own engine, file and state. When you remove one from the page, it frees the file that it held.