# 🚀 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.