@aloqabank/ui-kit

Modern React component library based on MUI (Material-UI) v7, featuring a comprehensive set of pre-built components and theme utilities.

Features

✨ 38+ Component Categories - Comprehensive UI component library 🎨 MUI v7 Based - Built on top of Material-UI with custom theme system 🎨 Figma Design Tokens - Automatic synchronization with Figma designs 🔧 TypeScript - Full type safety and IntelliSense support 🌐 Router Agnostic - Works with React Router, Next.js, Remix, and more 📦 Tree Shakable - Import only what you need 🎯 Production Ready - Battle-tested components 📚 Well Documented - Storybook documentation included

Installation

npm install @aloqabank/ui-kit
# or
yarn add @aloqabank/ui-kit
# or
pnpm add @aloqabank/ui-kit

Peer Dependencies

Make sure you have these peer dependencies installed:

npm install react react-dom @mui/material @emotion/react @emotion/styled

Quick Start

Basic Setup

Wrap your app with the ThemeProvider:

import { ThemeProvider, SettingsProvider } from '@aloqabank/ui-kit';

function App() {
  return (
    <ThemeProvider>
      <SettingsProvider>
        {/* Your app content */}
      </SettingsProvider>
    </ThemeProvider>
  );
}

export default App;

Using Components

All MUI components + custom components in one import!

import {
  Button,      // From MUI
  TextField,   // From MUI
  Box,         // From MUI
  Logo,        // Custom
  Label,       // Custom
  Iconify      // Custom
} from 'aloqabank-ui-kit';
import 'aloqabank-ui-kit/dist/aloqabank-ui-kit.css';

function Header() {
  return (
    <Box sx={{ p: 2 }}>
      <Logo />
      <Button variant="contained">MUI Button</Button>
      <Button variant="soft" color="success">Soft Button (Custom)</Button>
      <Label color="success">Active</Label>
      <Iconify icon="eva:home-fill" />
    </Box>
  );
}

Router Setup (Optional)

For navigation components, configure your router once:

import { setGlobalLink, setGlobalPathnameHook } from '@aloqabank/ui-kit';
import { Link, useLocation } from 'react-router-dom';

// Call once in your app setup
setGlobalLink(Link);
setGlobalPathnameHook(() => {
  const location = useLocation();
  return location.pathname;
});

Now navigation components like <Logo />, <MegaMenu />, and <CustomBreadcrumbs /> will automatically use your router!

Works with:

• ✅ React Router
• ✅ Next.js
• ✅ Remix
• ✅ TanStack Router
• ✅ Any routing library!

Design Tokens Integration

This library supports automatic synchronization with Figma design tokens. Update your designs in Figma, export the tokens, and see the changes reflected across all components!

import { useDesignTokens } from 'aloqabank-ui-kit';

function MyComponent() {
  const tokens = useDesignTokens();

  return (
    <Button
      sx={{
        background: tokens.gradient('primary.main'),
        '&:hover': {
          background: tokens.gradient('primary.bold'),
        },
      }}
    >
      Gradient Button
    </Button>
  );
}

Features:

• 🎨 Automatic gradient conversion from Figma
• 📏 Spacing and sizing tokens
• 🌈 Color palette synchronization
• 📝 Typography tokens
• 🔄 Live updates when tokens change

See Design Tokens Documentation for complete usage guide.

Available Components

Core Components

• Animate - Animation wrappers with Framer Motion
• Carousel - Embla carousel components
• Chart - ApexCharts wrappers
• Image - Optimized image component
• Logo - Customizable logo component
• Label - Badge/label component
• Iconify - Icon component with Iconify

Form Components

• FormProvider - React Hook Form context
• RHFTextField - Text field wrapper
• RHFCheckbox - Checkbox wrapper
• RHFSelect - Select wrapper
• RHFAutocomplete - Autocomplete wrapper
• RHFUpload - Upload wrapper
• And many more...

Navigation

• NavSection - Navigation section component
• NavBasic - Basic navigation
• MegaMenu - Mega menu component
• CustomBreadcrumbs - Breadcrumb navigation

Data Display

• Table - Enhanced table components
• CustomDataGrid - MUI Data Grid wrapper
• EmptyContent - Empty state component
• SearchNotFound - Search empty state

Advanced Components

• Editor - Rich text editor (Tiptap)
• Map - Map component (MapLibre GL)
• Lightbox - Image lightbox
• Markdown - Markdown renderer
• Upload - File upload component
• OrganizationalChart - Org chart component

Utilities

• Scrollbar - Custom scrollbar
• ProgressBar - Progress indicator
• LoadingScreen - Loading screen
• Snackbar - Toast notifications
• Settings - Settings drawer and context

See full component list →

Examples

Form with Validation

import { FormProvider, RHFTextField, RHFCheckbox } from '@aloqabank/ui-kit';
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';

const schema = z.object({
  email: z.string().email(),
  password: z.string().min(6),
  terms: z.boolean().refine(val => val === true),
});

function LoginForm() {
  const methods = useForm({
    resolver: zodResolver(schema),
  });

  return (
    <FormProvider methods={methods} onSubmit={methods.handleSubmit(onSubmit)}>
      <RHFTextField name="email" label="Email" />
      <RHFTextField name="password" label="Password" type="password" />
      <RHFCheckbox name="terms" label="I agree to terms" />
      <button type="submit">Login</button>
    </FormProvider>
  );
}

Chart Component

import { Chart, useChart } from '@aloqabank/ui-kit';

function SalesChart() {
  const chartOptions = useChart({
    xaxis: {
      categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
    },
  });

  return (
    <Chart
      type="line"
      series={[
        { name: 'Sales', data: [30, 40, 45, 50, 49] },
        { name: 'Revenue', data: [20, 30, 35, 40, 39] },
      ]}
      options={chartOptions}
      height={320}
    />
  );
}

Navigation Menu

import { MegaMenu } from '@aloqabank/ui-kit';

const menuData = [
  {
    title: 'Dashboard',
    path: '/dashboard',
    children: [
      { title: 'Analytics', path: '/dashboard/analytics' },
      { title: 'E-commerce', path: '/dashboard/ecommerce' },
    ],
  },
  // ... more items
];

function Navigation() {
  return <MegaMenu data={menuData} />;
}

Optional Dependencies

Some components require additional dependencies:

# For Forms
npm install react-hook-form @hookform/resolvers zod

# For Charts
npm install apexcharts react-apexcharts

# For Rich Text Editor
npm install @tiptap/react @tiptap/starter-kit

# For Carousel
npm install embla-carousel-react

# For Maps
npm install maplibre-gl react-map-gl

# For Icons
npm install @iconify/react

# For Data Grid
npm install @mui/x-data-grid

# For Date Pickers
npm install @mui/x-date-pickers dayjs

Theme Customization

import { ThemeProvider } from '@aloqabank/ui-kit';

function App() {
  return (
    <ThemeProvider
      themeOverrides={{
        palette: {
          primary: {
            main: '#1976d2',
          },
          secondary: {
            main: '#dc004e',
          },
        },
      }}
    >
      {/* Your app */}
    </ThemeProvider>
  );
}

TypeScript

This library is written in TypeScript and includes type definitions out of the box.

import type { LabelProps, ChartProps, ThemeOptions } from '@aloqabank/ui-kit';

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Requirements

• React 18+ or React 19+
• Node.js 20+
• MUI v7+

Documentation

• Storybook Documentation (coming soon)
• Router Integration Guide
• Component Examples

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

MIT © Aloqa Bank

Support

• 📧 Email: [email protected]
• 🐛 Issues
• 💬 Discussions

Links

• GitHub Repository
• NPM Package
• Changelog

Made with ❤️ by Aloqa Bank