@eml-payments/ui-kit

A fully-typed, design token-driven React UI Kit for modern web apps.
Built for fast integration, deep customization, and a great developer experience.

✨ Features

• Full TypeScript support — all types exported
• Design token based theming (via context provider)
• Easy theme override (colors, radius, fonts, etc)
• Composable, accessible components
• Ready-to-use Storybook with live playground
• Clean API, tree-shakable, zero CSS conflicts

🏗️ Tech Stack & Libraries

| Library | What we use it for | | --- | --- | | TailwindCSS | Utility-first styling, design tokens, and theming | | Radix UI | Accessible, unstyled primitive components (see below) | | Base UI | Headless primitive for the Combobox component | | Tanstack Table | Powerful headless table engine with sorting, filtering, and pagination | | Tanstack Virtual | Virtualized infinite scrolling for large table datasets | | react-day-picker | Calendar and date picking primitives | | dayjs | Lightweight date formatting, parsing, and manipulation | | intl-tel-input | International phone number input with country flags and validation | | class-variance-authority | Type-safe component variant definitions | | clsx + tailwind-merge | Conditional and conflict-free class name merging (cn() utility) | | lucide-react | Icon set used in Calendar, Combobox, and DatePicker | | react-icons | Icon set used across many components | | Storybook | Interactive component documentation and playground |

📦 Components

Radix UI Primitives

These components are built on top of Radix UI for accessible, composable behavior:

| Component | Radix Primitive | | --- | --- | | Accordion | @radix-ui/react-accordion | | Avatar | @radix-ui/react-avatar | | Button | @radix-ui/react-slot (for asChild composition) | | Checkbox | @radix-ui/react-checkbox | | Dialog | @radix-ui/react-dialog | | Dropdown | @radix-ui/react-dropdown-menu | | Label | @radix-ui/react-label | | Popover | @radix-ui/react-popover | | RadioGroup | @radix-ui/react-radio-group | | Select / SelectWrapper | @radix-ui/react-select | | Switch | @radix-ui/react-switch | | Tabs | @radix-ui/react-tabs | | Tooltip | @radix-ui/react-tooltip |

Data Table

| Component | Powered by | | --- | --- | | Table | @tanstack/react-table for headless table logic (sorting, filtering, pagination) and @tanstack/react-virtual for infinite scroll virtualization |

Date & Time

| Component | Powered by | | --- | --- | | Calendar | react-day-picker + lucide-react icons | | DatePicker | react-day-picker + dayjs for date formatting |

Specialized Inputs

| Component | Powered by | | --- | --- | | Combobox | @base-ui/react (headless combobox primitive) + lucide-react icons | | PhoneInput | intl-tel-input (international phone input with country flags) | | InputGroup | class-variance-authority for variant styling |

Custom-built Components

These components are built from scratch with React and TailwindCSS (no external primitive library):

Alert · ButtonGroup · Card · CopyButton · Counter · CreditCard · Divider · DropdownWrapper · Ellipsis · Input · Pills · SearchInput · Skeleton · Spinner · Stepper · Textarea · UICreditCard

🚀 Installation

npm install @eml-payments/ui-kit

Note:
You must also have react and react-dom (v18+), and TailwindCSS set up in your app.

🎨 Usage

1. Import the CSS for styles and tokens:

import '@eml-payments/ui-kit/style.css';

2. Wrap your app in the UIKitProvider (optional: pass your design tokens):

import React from 'react';
import { UIKitProvider } from '@eml-payments/ui-kit';

const theme = {
	colors: {
		primary: { light: "#0A5FFF", dark: "#7c80f8" },
		success: { light: "#12D176", dark: "#16c784" },
		error: '#d7263d',
		// ...override any design token here
	},
	radius: '10px',
	fontFamily: 'Inter, sans-serif',
};

export default function App() {
	return <UIKitProvider config={theme}>{/* Your app code */}</UIKitProvider>;
}

3. Use components anywhere under the provider:

import { Button, Input, Table } from "@eml-payments/ui-kit";

<Button variant="primary">Primary Button</Button>
<Input label="Email" placeholder="[email protected]" />

🛠️ Theming & Configuration

You can fully override the theme tokens using the config prop:

type UIKitConfig = {
	colors?: {
		primary?: string | { light: string; dark: string };
		secondary?: string | { light: string; dark: string };
		accent?: string | { light: string; dark: string };
		success?: string | { light: string; dark: string };
		warning?: string | { light: string; dark: string };
		error?: string | { light: string; dark: string };
		[key: string]: string | undefined;
	};
	radius?: string; // e.g. "8px"
	fontFamily?: string;
	// ...extend as needed
};

Any value not set falls back to a sensible default.

📚 Documentation & Storybook

• Interactive Docs & Playground:
  run locally: npm run storybook

🧩 Example: Table

import { Table } from '@eml-payments/ui-kit';

const columns = [
	{ header: 'Name', accessorKey: 'name' },
	{ header: 'Email', accessorKey: 'email' },
];
const data = [
	{ name: 'Alice', email: '[email protected]' },
	{ name: 'Bob', email: '[email protected]' },
];

<Table columns={columns} data={data} />;

📝 License

MIT © EML Payments