Integration guide

ImportReady is a self-hosted commercial source kit. This page explains the actual v1 API.

Get started

Copy the kit's src folder into your app assets, load the ES module, and add the custom element. Serve files over HTTP or HTTPS.

<import-ready brand="Your product"></import-ready>
<script type="module">
  import '/assets/importready/import-ready.js';
  const importer = document.querySelector('import-ready');
  importer.schema = [
    {key:'name', type:'text', required:true},
    {key:'email', type:'email', required:true, unique:true}
  ];
  importer.addEventListener('importready:complete', ({detail}) => {
    // Use your authenticated API client. Validate again on the server.
    console.log(detail.records, detail.skipped);
  });
</script>

Field rules

Rule	Behavior
type	text, email, number, integer, date, boolean, enum
required / unique	Require a value / enforce uniqueness within the file
aliases	Additional names used by exact normalized header matching
min / max / maxLength	Numeric bounds / maximum text length
decimal	Dot by default; explicitly set comma for decimal-comma numbers. No thousands separators.
format	YYYY-MM-DD or DD/MM/YYYY. Invalid calendar dates fail.
values	Allowed strings for enum fields

Branding and events

Set the brand attribute and the --ir-accent CSS custom property. Set schema as a JavaScript property. The component emits importready:complete with {records, skipped}. This event means local validation passed, not that your database accepted records.

Headless core

import {parseCSV, autoMap, validateRows} from './src/core.js';
const parsed = parseCSV(csvText);
const mapping = autoMap(parsed.headers, schema);
const result = validateRows(parsed, schema, mapping);
// result.valid, result.invalid, result.duplicates

Frameworks

React: import on the client, set schema through a ref and attach/remove the native event listener in an effect. Vue: configure import-ready as a custom element and set the DOM property after mounting. Laravel: load the module in Blade and use your existing authenticated endpoint with CSRF protection. The included runnable integration is plain JavaScript; framework wrappers have not been separately tested.

Limits and safety

UTF-8 CSV only. Up to 5 MB, 10,000 rows, 100 columns. Demo limit: 100 rows.
No XLSX, UTF-16, streaming or database integration. Parsing is synchronous.
Review displays 100 rows at a time, invalid first. The report includes every invalid row.
Rows with the wrong number of cells must be corrected in the source file.
Optional blanks become null. Emails are normalized to lowercase.
Duplicates are checked inside the current file. With skipping on, the first fully valid occurrence wins.
CSV exports prefix possible spreadsheet formulas with an apostrophe, including negative numeric text. Use JSON to preserve exact types.
No file data is sent by the component. Your integration controls subsequent network requests.
Always revalidate, authorize and apply database constraints on the server.