Upload widget

@constaia/widget is a web component, <constaia-upload>, that captures a document in the browser, checks the photo quality and sends it to your backend. Your backend calls Constaia with the key and returns the result, which the widget shows as Valid, Invalid or Review with its reasons. Current version: 0.1.0.

• No dependencies, about 13 kB compressed. Works in any framework, with React and Vue wrappers.
• Drag and drop, file picker and camera on phones. JPEG, PNG, WEBP, HEIC and PDF up to 20 MB.
• ID-1 card framing guide, client-side quality check and front + back capture.
• Real upload progress, accessible (keyboard, aria-live, verdicts with icon and text) and in es, en, pt, fr.

InstallationCopy Anchor Link

npm install @constaia/widget

import "@constaia/widget"; // registers <constaia-upload>

How it worksCopy Anchor Link

1. The user picks or photographs the document. For Spanish DNI, NIE and EU ID cards, the widget asks for front and back and merges them into a single JPEG.
2. The widget checks quality (resolution, blur, brightness) and warns before uploading.
3. It sends POST multipart/form-data to your endpoint with two fields: file and options.
4. Your backend calls POST /v1/analyze, deciding itself expect and checks, and returns the analysis as JSON.
5. The widget shows the verdict, reasons and warnings, and fires constaia:result.

Minimal exampleCopy Anchor Link

<script type="module" src="https://cdn.jsdelivr.net/npm/@constaia/widget@0.1"></script>

<constaia-upload endpoint="/api/constaia" document="es_dni" lang="en"></constaia-upload>

<script type="module">
  const el = document.querySelector("constaia-upload");
  el.addEventListener("constaia:result", (e) => {
    console.log(e.detail.id, e.detail.verdict?.status); // "valid" | "invalid" | "review"
  });
  el.addEventListener("constaia:error", (e) => console.warn(e.detail.code, e.detail.message));
</script>

And the backend (Node, with the JavaScript SDK):

import express from "express";
import multer from "multer";
import { Constaia, ConstaiaError } from "@constaia/sdk";

const app = express();
const upload = multer({ storage: multer.memoryStorage(), limits: { fileSize: 20 * 1024 * 1024 } });
const constaia = new Constaia();

app.post("/api/constaia", upload.single("file"), async (req, res) => {
  if (!req.file) return res.status(400).json({ error: { message: "The document is missing." } });
  try {
    const analysis = await constaia.analyze(req.file.buffer, {
      filename: req.file.originalname,
      expect: ["es_dni", "es_nie", "passport"], // decided by the server, not the browser
      checks: { notExpired: true },
      language: "en",
    });
    res.json(analysis);
  } catch (err) {
    const status = err instanceof ConstaiaError && err.status && err.status < 500 ? 422 : 502;
    res.status(status).json({ error: { message: "We couldn't analyze the document." } });
  }
});

app.listen(3000);

Full framework guides in Integrations.

Contract with your backendCopy Anchor Link

AttributesCopy Anchor Link

Properties and methodsCopy Anchor Link

Properties: the attributes in camelCase (maxSizeMb, autoSubmit…), plus headers (object), messages (texts), and read-only status, result and error.

Methods: submit(), reset(), selectFile(file, side?) and open(camera?).

const el = document.querySelector("constaia-upload");
el.headers = { "X-CSRF-TOKEN": token };
el.reset();

EventsCopy Anchor Link

All are CustomEvents with bubbles and composed.

Front and backCopy Anchor Link

For two-sided cards the widget asks for the front, then the back, and merges them on the client into one JPEG (front on top, back below, quality 0.9, max. 2000 px wide), because the API takes a single file.

• If the front is a PDF, the back is not requested: the PDF is sent as is (it should contain both sides).
• If the back is a PDF or the browser cannot decode an image (e.g. HEIC outside Safari), only the front is sent and a notice is shown. The API may then return the side_missing warning.

Quality checkCopy Anchor Link

Before uploading an image, the widget downsizes it to 1024 px and measures the original resolution (short side under 600 px → low_resolution), blur (variance of the Laplacian), brightness and, for cards, glare. If there are issues, the user sees Upload anyway and Retake. PDFs skip this step; the API runs its own checks.

StylingCopy Anchor Link

constaia-upload {
  --constaia-accent: #12b76a;
  --constaia-accent-fg: #0b1220;
  --constaia-bg: #fafaf7;
  --constaia-fg: #0b1220;
  --constaia-surface: #ffffff;
  --constaia-muted: #5b6474;
  --constaia-border: #d5d9df;
  --constaia-radius: 12px;
  --constaia-font: Inter, system-ui, sans-serif;
  --constaia-valid: #12b76a;
  --constaia-invalid: #e5484d;
  --constaia-review: #f5a524;
  --constaia-focus: #12b76a;
}
constaia-upload::part(dropzone) { border-style: solid; }

Parts: container, dropzone, frame, button, button-primary, camera-button, preview, thumbnail, quality, progress, progress-bar, result, verdict, reasons, warnings, note, error.

TextsCopy Anchor Link

document.querySelector("constaia-upload").messages = {
  dropTitle: "Upload your medical certificate",
  verdictValid: "All good",
};

Keys are those of LOCALES.es, exported by the package (dropTitle, dropHint, chooseFile, takePhoto, verdictValid, verdictInvalid, verdictReview, tryAgain…).

ReactCopy Anchor Link

"use client";
import { ConstaiaUpload, useConstaiaUpload } from "@constaia/widget/react";

export function VerifyId() {
  return (
    <ConstaiaUpload
      endpoint="/api/constaia"
      document="es_dni"
      lang="en"
      onResult={(analysis) => console.log(analysis.verdict?.status)}
      onError={(error) => console.warn(error.code)}
    />
  );
}

export function VerifyWithHook() {
  const { ref, status, result, error, reset } = useConstaiaUpload({ endpoint: "/api/constaia", document: "es_dni" });
  return (
    <>
      <ConstaiaUpload ref={ref} />
      <p>{status} {result?.verdict?.status} {error?.message}</p>
      <button type="button" onClick={reset}>Try again</button>
    </>
  );
}

Props: the attributes in camelCase (endpoint, expect, document, sides, frame, accept, maxSizeMb, autoSubmit, withCredentials, lang, theme, camera, messages, headers) and the callbacks onFile, onQuality, onProgress, onResult, onError, onStatus. Works with React 18 and 19 and with server rendering (the element is only registered in the browser).

VueCopy Anchor Link

<script setup lang="ts">
import { ConstaiaUpload } from "@constaia/widget/vue";

function onResult(analysis: { verdict?: { status: string } | null }) {
  console.log(analysis.verdict?.status);
}
</script>

<template>
  <ConstaiaUpload endpoint="/api/constaia" expect="medical_certificate_sport" lang="en" @result="onResult" />
</template>

Events: @file, @quality, @progress, @result, @error, @status. To use the <constaia-upload> tag directly, install ConstaiaPlugin and tell the compiler it is a custom element:

vue({ template: { compilerOptions: { isCustomElement: (tag) => tag.startsWith("constaia-") } } });

Svelte, Angular and othersCopy Anchor Link

Import @constaia/widget once (it registers the element) and use the tag. Listen to events with addEventListener, because the names contain a colon (constaia:result). In Angular, add CUSTOM_ELEMENTS_SCHEMA to the component. Examples in Svelte and Angular.

Next stepsCopy Anchor Link