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");Attributes and scalar properties
Section titled “Attributes and scalar properties”| 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.
Object properties
Section titled “Object properties”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.
Read-only state
Section titled “Read-only state”| 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.
Methods
Section titled “Methods”| 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 });Events and React callbacks
Section titled “Events and React callbacks”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.
Refused settings
Section titled “Refused settings”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,cancelLabelandvalidationHooksproperties, andnotify(), throw aTypeErrorat once.open()returns a rejected promise with one, and so does the firstnext()ofbatches(). The message names the setting and the first problem, for exampleschema.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.
Sizing it
Section titled “Sizing it”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.
Panels
Section titled “Panels”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
Section titled “Features”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. |
File settings
Section titled “File settings”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.
Duplicate scan
Section titled “Duplicate scan”Set duplicateScan to find repeated rows in each read. Then
skipDuplicates works without a
scan in the Import step.
keysholds 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 asemailandemail_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.keepis the copy that stays:first, the default, orlast.
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.
Styling
Section titled “Styling”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
Section titled “Tokens”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
Section titled “Stylesheet”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) |
Messages
Section titled “Messages”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 on one page
Section titled “Two importers on one page”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.