Documentation

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.

1

Install the package

Terminalbash
npm install @xlork/react
2

Add the component

App.jsxjsx
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);
      }}
    />
  );
}
3

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.

npmbash
npm install @xlork/react
pnpmbash
pnpm add @xlork/react
yarnbash
yarn add @xlork/react

Requirements: 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:

Full XLorkClient Examplejsx
<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.

Column definitionjs
{
  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 only
dateDate with configurable format
emailEmail validation
dropdownSelect from predefined options
selectSingle selection
autocompleteAuto-suggest from list
urlURL validation
ipIP address format

Validators

Add validation rules to columns. Each validator can include a custom error message.

requiredvalidator

Field must have a value

{ validate: "required" }
requiredWithoutvalidator

Required if specified fields are empty

{ requiredWithout: ["Latitude", "Longitude"] }
regexMatchesvalidator

Value must match regex pattern

{ regexMatches: "^\\d{1,2}$" }
regexExcludesvalidator

Value must not match pattern

{ regexExcludes: "badword" }
minLengthvalidator

Minimum character count

{ minLength: 3 }
maxLengthvalidator

Maximum character count

{ maxLength: 100 }

Settings Reference

Pass these inside the settings prop to customize the importer.

PropTypeDefaultDescription
titlestring"Upload Data"Title shown in the importer header
sampleUrlstringURL to a sample file users can download
maxRecordsnumberMaximum rows allowed per import
allowInvalidSubmitbooleanfalseAllow submitting data with validation errors
languagestring"en"Interface language (en, es, fr, de, etc.)
historybooleanfalseEnable import history for the user
themestring"SKYBLUE"Color theme — see Themes section for all 16 options
developmentbooleanfalseEnable development/debug mode
displaystring"popup"Display mode: "popup" or "inline"
headerbooleantrueShow/hide the importer header bar
socialbooleantrueShow/hide social/branding footer
themeColorstringCustom hex color for the importer theme (e.g. "#6366f1")
brandingstringCustom logo URL displayed in the importer header
scrapperbooleanfalseEnable the Google Sheets scrapper integration
multilingualobjectLanguage config object, e.g. { default_language: "af" }

Themes

Set the theme setting to change the importer's appearance.

GRAPFRUITFLATREDFLATORANGEAQUAMINTLIMEFLATMINTBLUEJEANSSKYBLUEGRASSSUNFLOWERBITTERSWEETPINKROSELIGHTPINKDARKGRAYFLATGRAY
Theme usagejsx
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.

Callback examplesjsx
// 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.

Open Sandbox

Need help? Reach out at support@xlork.com or check the pricing page for enterprise support options.