@xlork/react/dist/README.md

XLork is a powerful Node.js package for parsing and manipulating CSV and XML files. With its intuitive API, XLork makes it easy to read, write, and modify CSV and XML data in your Node.js applications. Whether you're dealing with large datasets or just ne

# 🚀 XLork Client

**XLork Client** is a plug-and-play Node.js / React component for integrating the [XLork](https://xlork.com) data upload service. Collect, validate, and receive structured data from your users in a beautiful, customizable UI. Install [XLork](https://xlork.com) today and start Simplify Data Integration with data onboarding.

[![NPM Version](https://img.shields.io/npm/v/@xlork/react.svg)](https://www.npmjs.com/package/@xlork/react)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
[![XLork](https://img.shields.io/badge/powered%20by-XLork-blueviolet)](https://xlork.com)

---

## 📦 Installation

```bash
npm install @xlork/react
```

---

## ⚡ Quick Start

```jsx
import React from "react";
import {XlorkClient} from "@xlork/react";

function App() {
	const settings = {
		title: "Upload Your Data",
		columns: [
			{
				label: "Name",
				key: "name",
			},
			{
				label: "Email",
				key: "email",
			},
			{
				label: "DOB",
				key: "date",
				type: "date",
				format: "YYYY-MM-DD",
			},
			{
				label: "Address",
				key: "address",
				validators: {
					required: true,
					error: "Address can not be blank",
				},
			},
			{
				label: "Status",
				key: "status",
				type: "select",
				options: {
					0: "Active",
					1: "Inactive",
					3: "Pending",
				},
			},
			{
				label: "Address Type",
				key: "type",
				type: "dropdown",
				options: ["home", "office"],
				defaultValue: "home",
			},
		],
	};

	const user = {
		email: "user@example.com",
	};

	const handleComplete = (data) => {
		console.log("✅ Upload completed:", data);
	};

	const handleCancel = () => {
		console.log("❌ Upload cancelled");
	};

	return (
		<XlorkClient
			licenseKey="your-license-key"
			user={user}
			settings={settings}
			onComplete={handleComplete}
			onCancel={handleCancel}
		/>
	);
}

export default App;
```

---

## ⚙️ Props

| Prop           | Type        | Required | Description                                 |
| -------------- | ----------- | -------- | ------------------------------------------- |
| `licenseKey`   | `string`    | ✅       | Your **XLork** license key                  |
| `user`         | `object`    | ✅       | User object with at least an `email` field  |
| `settings`     | `object`    | ⚠️       | Optional UI & behavior config               |
| `onComplete`   | `function`  | ⚠️       | Callback triggered when upload completes    |
| `onCancel`     | `function`  | ⚠️       | Callback triggered when upload is cancelled |
| `origin`       | `string`    | ❌       | Custom backend URL if self-hosted           |
| `children`     | `ReactNode` | ❌       | Render custom trigger (e.g. a button)       |
| `loadOnDemand` | `function`  | ❌       | Use to programmatically trigger upload      |

---

## 🛠️ Settings Object

Customize the behavior and appearance of the upload widget using the `settings` prop:

```js
{
	title: "Upload Data",         // Form title
	columns: [                    // Field definitions
		{ label: "Name", key: "name" },
		{ label: "Email", key: "email" }
	],
	display: "popup",             // 'popup' or 'inline'
	header: true,                 // Show header text
	branding: false,              // Show 'Powered by XLork'
	history: false,               // Enable upload history
	social: true                  // Show social share options
	allowInvalidSubmit: true,     // Allow submission of invalid records
	theme: null,                  // Custom theme (if available)
	maxRecords: 0,                // 0 means no limit
	sampleUrl: null,              // Optional sample file URL

}
```

---

## 🌟 Features

✅ **Easy integration** — drop in a component and start accepting data.  
✅ **Built-in validation** — ensure data integrity at source.  
✅ **Highly customizable** — adapt styling, columns, and behavior as needed.  
✅ **Upload history** — users can review their upload sessions (optional).  
✅ **Supports large data sets** — efficiently handles large files.  
✅ **Self-host or cloud** — flexible deployment options.

---

## 🧠 Tips & Best Practices

- Use `display: "inline"` to embed the uploader into the page.
- Add `sampleUrl` to help users with formatting.
- Use `loadOnDemand` to decouple the uploader from UI buttons.

---

## 📜 License

MIT © [Xlork.com](https://xlork.com)

---

## 🌐 Links

- 🌍 [Website](https://xlork.com)
- 📚 [Documentation](https://xlork.com/docs)
- 🧪 [Playground](https://codesandbox.io/p/sandbox/xlork-react-latest-exvsu1)
- 🎥 [YouTube Demo](https://www.youtube.com/watch?v=7rfdrThZ4xY&ab_channel=Xlork)

## 💼 Who’s using XLork?

Companies like **Zeo**, **Konnector**, **LeadRouter**, **[Dolr.in](https://dolr.in)**, and many others trust XLork for their data onboarding needs.