Skip to content
demuddler

Frameworks

Add the importer to React, Next.js, Vue, Svelte, Angular, Astro or plain JavaScript. Examples cover setup, events and row delivery.

Every framework uses the same <demuddler-importer> element. React has its own adapter. Other frameworks set object properties and listen for DOM events. Complete Install first.

The examples on this page share this module. Create customer-import.ts next to your component, and replace the licence key. The receive function counts the rows and does not save them. To save rows, see Deliver rows.

import type { ImportResult, ImporterSchema } from "@demuddler/importer";
export const licenceKey = "YOUR_LICENCE_KEY";
export const schema: ImporterSchema = {
fields: [
{
key: "email",
dtype: "text",
rules: [{ type: "required" }, { type: "format", format: "email" }],
},
{ key: "name", dtype: "text" },
],
};
export async function receive(result: ImportResult): Promise<void> {
let count = 0;
for await (const batch of result.batches({ size: 500 })) {
count += batch.rows.length;
}
document.querySelector("#import-status")?.replaceChildren(`Received ${count} rows.`);
}

The examples show one importer on each page. For more than one, give each status element its own ID, or use component state.

Use the example in Install. A page that your server renders, for example in Rails or Django, needs a browser bundle or an import map to load the package.

The adapter needs React 18 or later. It sets the object properties, gives typed callbacks and waits for the promise that onComplete returns.

"use client";
import { DemuddlerImporter } from "@demuddler/importer/react";
import { licenceKey, receive, schema } from "./customer-import";
export default function ImportCustomers() {
return (
<section>
<DemuddlerImporter
licenceKey={licenceKey}
schema={schema}
onComplete={receive}
style={{ height: 640 }}
/>
<p id="import-status" role="status">
Choose a file to start.
</p>
</section>
);
}

When you pass onComplete, the adapter turns on handoff. When you pass onCancel, it shows the cancel control. When you pass onFullScreen, it shows the Full screen button, and isFullScreen sets its state. To remove the file downloads, so that delivery to your page is the only finish action, pass noFile. The component reference lists every prop.

The adapter sets only the object props that have a value. If you change a prop to undefined, the earlier value stays. Give the new value, or remount the component.

For the Next.js App Router, keep the component behind the use client boundary. Create the completion handler in client code. A Server Component cannot pass a function as a prop.

Keep the importer mounted while the returned promise runs. If a loading state replaces the component, the page loses the frame and its result.

Tell the template compiler that the tag is a custom element. Add this option to your vite.config.ts:

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
export default defineConfig({
plugins: [
vue({
template: {
compilerOptions: {
isCustomElement: (tag) => tag === "demuddler-importer",
},
},
}),
],
});

app.config.compilerOptions alone does not apply to precompiled .vue files. See the Vue guide to custom elements.

<script setup lang="ts">
import "@demuddler/importer";
import type { DemuddlerEventMap } from "@demuddler/importer";
import { licenceKey, receive, schema } from "./customer-import";
function onComplete(event: Event) {
const { detail } = event as DemuddlerEventMap["complete"];
detail.waitUntil(receive(detail.result));
}
</script>
<template>
<demuddler-importer
:schema.prop="schema"
:licence-key="licenceKey"
handoff
@complete="onComplete"
style="height: 640px"
/>
<p id="import-status" role="status">Choose a file to start.</p>
</template>

The .prop modifier sets the schema as an object. Use it for every object setting, such as appearance, features and fileSettings.

Set the properties and add the listener in onMount. It does not run during server rendering. The function that it returns removes the listener.

<script lang="ts">
import { onMount } from "svelte";
import "@demuddler/importer";
import type { DemuddlerImporterElement, DemuddlerEventMap } from "@demuddler/importer";
import { licenceKey, receive, schema } from "./customer-import";
let importer: DemuddlerImporterElement;
onMount(() => {
importer.schema = schema;
const complete = (event: DemuddlerEventMap["complete"]) => {
event.detail.waitUntil(receive(event.detail.result));
};
importer.addEventListener("complete", complete);
return () => importer.removeEventListener("complete", complete);
});
</script>
<demuddler-importer bind:this={importer} licence-key={licenceKey} handoff style="height: 640px"
></demuddler-importer>
<p id="import-status" role="status">Choose a file to start.</p>

If your schema changes, assign a new object. Add each listener once, and remove it on unmount.

Allow the tag with CUSTOM_ELEMENTS_SCHEMA. A property binding sets the schema object.

import { Component, CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
import "@demuddler/importer";
import type { DemuddlerEventMap } from "@demuddler/importer";
import { licenceKey, receive, schema } from "./customer-import";
@Component({
selector: "app-customer-import",
standalone: true,
schemas: [CUSTOM_ELEMENTS_SCHEMA],
template: `
<demuddler-importer
[schema]="schema"
[attr.licence-key]="licenceKey"
handoff
(complete)="onComplete($event)"
style="height: 640px"
></demuddler-importer>
<p id="import-status" role="status">Choose a file to start.</p>
`,
})
export class CustomerImportComponent {
readonly schema = schema;
readonly licenceKey = licenceKey;
onComplete(event: Event): void {
const { detail } = event as DemuddlerEventMap["complete"];
detail.waitUntil(receive(detail.result));
}
}

In an application that uses NgModule, add CUSTOM_ELEMENTS_SCHEMA to the module that owns the template.

Use a normal client script, so that Astro bundles the package. A script with is:inline cannot import a bare package name.

<demuddler-importer style="height: 640px" handoff></demuddler-importer>
<p id="import-status" role="status">
Choose a file to start.
</p>
<script>
import "@demuddler/importer";
import { licenceKey, receive, schema } from "./customer-import";
const importer = document.querySelector("demuddler-importer");
if (importer) {
importer.licenceKey = licenceKey;
importer.schema = schema;
importer.addEventListener("complete", ({ detail }) => {
detail.waitUntil(receive(detail.result));
});
}
</script>

With view transitions, a script runs only on the first page load. Set up each new importer element yourself, and remove the old listeners.

You can import the loader on the server, where HTMLElement and customElements do not exist. The server renders the tag, and the browser starts the frame. Put code that uses files, the DOM or browser storage in client code.

The package includes its types. document.querySelector("demuddler-importer") returns the typed element or null, and its event details are typed. For a query by ID, give the element type.