Everything you need, nothing you don't
Columns, validators, themes, callbacks — it's all here. Follow the guide below to integrate Xlork into your React app and start importing CSV, Excel, and Google Sheets data in minutes.
Quick Start
Get up and running with Xlork in three simple steps.
Install the package
npm install @xlork/reactAdd the component
import { XLorkClient } from "@xlork/react";
export default function App() {
return (
<XLorkClient
licenseKey="XXXX-XXXX-XXXX-XXXX"
user={{ email: "user@example.com", name: "User" }}
settings={{
columns: [
{ label: "Name", key: "name" },
{ label: "Email", key: "email", validators: { validate: "required" } },
],
title: "Import Contacts",
}}
onComplete={async (response) => {
console.log("Imported data:", response);
}}
/>
);
}Get your free license key
Sign up at xlork.com/app/account to get your license key and replace the placeholder above. Free tier includes 10 rows per import.
Installation
Xlork is available as an npm package for React projects.
npm install @xlork/reactpnpm add @xlork/reactyarn add @xlork/reactRequirements: React 16.8+ (hooks support). Works with Next.js, Vite, Create React App, and any React framework.
Full Integration Example
Here's a complete example with columns, validators, settings, callbacks, and a custom trigger button using loadOnDemand:
<XLorkClient
licenseKey="XXXX-XXXX-XXXX-XXXX"
user={{
email: "docs-react@xlork.com",
name: "Free user",
}}
settings={{
columns: [
{
label: "Address",
key: "address",
type: "text",
validators: {
requiredWithout: ["Latitude", "Longitude"],
error: "Required if latitude and longitude not available."
}
},
{ label: "Latitude", key: "latitude", type: "text" },
{ label: "Longitude", key: "longitude" },
{ label: "Country", key: "country" },
{
label: "Order Type",
key: "type",
type: "dropdown",
options: ["home", "office"],
},
{
label: "Email",
key: "email",
validators: { validate: "required" },
},
{ label: "Name", key: "name" },
{
label: "Duration",
key: "stop_duration",
validators: {
regexMatches: "^null|^$|\\d{1,2}$",
error: "Only numbers, max 2 digits."
}
},
{
label: "Stop date",
key: "stop_date",
type: "date",
dateFormat: "DD/MM/YYYY"
}
],
title: "Orders",
sampleUrl: "sample.xlsx",
maxRecords: 2000,
allowInvalidSubmit: true,
language: "en",
history: true,
theme: "SKYBLUE",
development: true,
display: "inline",
header: false,
social: false,
}}
onComplete={async (response) => {
console.log(response);
}}
onCancel={() => {
console.log("Import cancelled");
}}
loadOnDemand={(init) => (
<button onClick={() => init()}>
Upload
</button>
)}
/>Column Configuration
Define columns to map imported data to your schema. Each column needs a label and key.
{
label: "Email", // Display name in the mapper
key: "email", // Key in the output data
type: "email", // Column type (see below)
validators: { // Optional validation rules
validate: "required"
}
}Supported Column Types
textPlain text input (default)numericNumeric values onlydateDate with configurable formatemailEmail validationdropdownSelect from predefined optionsselectSingle selectionautocompleteAuto-suggest from listurlURL validationipIP address formatValidators
Add validation rules to columns. Each validator can include a custom error message.
requiredvalidatorField must have a value
{ validate: "required" }requiredWithoutvalidatorRequired if specified fields are empty
{ requiredWithout: ["Latitude", "Longitude"] }regexMatchesvalidatorValue must match regex pattern
{ regexMatches: "^\\d{1,2}$" }regexExcludesvalidatorValue must not match pattern
{ regexExcludes: "badword" }minLengthvalidatorMinimum character count
{ minLength: 3 }maxLengthvalidatorMaximum character count
{ maxLength: 100 }Settings Reference
Pass these inside the settings prop to customize the importer.
| Prop | Type | Default | Description |
|---|---|---|---|
title | string | "Upload Data" | Title shown in the importer header |
sampleUrl | string | — | URL to a sample file users can download |
maxRecords | number | — | Maximum rows allowed per import |
allowInvalidSubmit | boolean | false | Allow submitting data with validation errors |
language | string | "en" | Interface language (en, es, fr, de, etc.) |
history | boolean | false | Enable import history for the user |
theme | string | "SKYBLUE" | Color theme — see Themes section for all 16 options |
development | boolean | false | Enable development/debug mode |
display | string | "popup" | Display mode: "popup" or "inline" |
header | boolean | true | Show/hide the importer header bar |
social | boolean | true | Show/hide social/branding footer |
themeColor | string | — | Custom hex color for the importer theme (e.g. "#6366f1") |
branding | string | — | Custom logo URL displayed in the importer header |
scrapper | boolean | false | Enable the Google Sheets scrapper integration |
multilingual | object | — | Language config object, e.g. { default_language: "af" } |
Themes
Set the theme setting to change the importer's appearance.
settings={{
theme: "SKYBLUE",
// Available: GRAPFRUIT | FLATRED | FLATORANGE | AQUA | MINT | LIME
// FLATMINT | BLUEJEANS | SKYBLUE | GRASS | SUNFLOWER
// BITTERSWEET | PINKROSE | LIGHTPINK | DARKGRAY | FLATGRAY
// ...other settings
}}Callbacks
Handle import completion, cancellation, and lazy loading with these callback props.
onComplete(response)Called when the user submits imported data. Receives the mapped rows as an array.
onCancel()Called when the user closes the importer without submitting.
loadOnDemand(init)Render your own trigger button. Call init() to open the importer.
// onComplete — fires when user finishes import
onComplete={async (response) => {
// response contains the imported rows
await fetch("/api/import", {
method: "POST",
body: JSON.stringify(response),
});
}}
// onCancel — fires when user closes without submitting
onCancel={() => {
console.log("User cancelled the import");
}}
// loadOnDemand — render your own trigger button
loadOnDemand={(init) => (
<button onClick={() => init()}>
Open Importer
</button>
)}Sandbox & Live Demo
Fork the CodeSandbox to experiment with the XLorkClient component and all its options in a live environment.
Try it on CodeSandbox
Fork the XLorkClient component and play with columns, validators, themes, and display modes. No setup required.
Need help? Reach out at support@xlork.com or check the pricing page for enterprise support options.