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.
Shared example module
Section titled “Shared example module”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.
Plain JavaScript or TypeScript
Section titled “Plain JavaScript or TypeScript”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.
React and Next.js
Section titled “React and Next.js”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.
Vue 3 with Vite
Section titled “Vue 3 with Vite”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.
Svelte and SvelteKit
Section titled “Svelte and SvelteKit”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.
Angular standalone component
Section titled “Angular standalone component”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.
Server rendering and TypeScript
Section titled “Server rendering and TypeScript”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.