mango-ui-kit

v3.5.0

Published

8 days ago

A premium, modern React component library with a built-in zero-dependency theme engine. 40+ components, TypeScript-first, dark mode ready.

0High
0Medium
0Low

nitishroy7033

react ui ui-kit components typescript design-system dark-mode theme theming css-variables premium-ui mango

Mango UI Kit 🥭

The Ultimate Premium, Vibrant, and High-Performance React Component Library

Mango UI Kit is a state-of-the-art design system crafted for modern web applications. 40+ production-ready components with a fully generic, zero-dependency theme engine built right in.

📖 Table of Contents

✨ Key Features

🌈 Design System

Varied Palettes: Solid, Outlined, Soft (Glassmorphic), and Gradient styles out of the box.
Vibrant Gradients: Built-in "Mango" flavored gradients that breathe life into buttons and loaders.
Micro-Animations: Custom cubic-bezier transitions for every interaction.

🛠 Architecture

React 18 / 19 Ready: Optimized for concurrent rendering.
Zero-Dependency Theme Engine: No external theming library needed — colors, sizes, and custom tokens all managed in one place.
TypeScript First: Every prop, every token, fully typed with IntelliSense.
Tailwind Friendly: Drop into any existing Tailwind project without conflicts.

🚀 Quick Start

1. Install

# npm
npm install mango-ui-kit

# yarn
yarn add mango-ui-kit

# pnpm
pnpm add mango-ui-kit

2. Import base styles

Add this once in your entry file (main.tsx, index.ts, or _app.tsx):

import 'mango-ui-kit/dist/mango-ui-kit.css';

3. Start using components

import { Button, Box } from 'mango-ui-kit';

export default function App() {
  return (
    <Box p="20px">
      <Button variant="primary" onClick={() => alert('Hello Mango!')}>
        Get Started
      </Button>
    </Box>
  );
}

🎨 Complete Theme Management

Mango UI Kit ships a fully generic, built-in theme engine — no Styled Components, no Emotion, no external library needed.

It manages:

🌓 Light & Dark modes — two separate token sets, switch instantly
💾 Persistence — mode is saved to localStorage automatically
💉 CSS variable injection — every token becomes a global CSS variable on <html>
🎨 Custom tokens — define your own colors, sizes, spacing with any name you want
🪝 useTheme hook — access all tokens directly in TSX/JS

Step 1 — Wrap your App

// main.tsx
import { ThemeProvider } from 'mango-ui-kit';
import 'mango-ui-kit/dist/mango-ui-kit.css';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <ThemeProvider defaultThemeMode="light" storageKey="my-app-theme">
    <App />
  </ThemeProvider>
);

ThemeProvider Props:

Step 2 — Define your brand theme

The ThemeConfig accepts three buckets per mode:

import type { ThemeConfig } from 'mango-ui-kit';

const myTheme: Partial<ThemeConfig> = {
  light: {

    // ── Override built-in color tokens ─────────────────────
    colors: {
      primaryColor: '#7c3aed',          // Your brand purple
      lightPrimaryColor: '#f5f3ff',     // Soft tint of primary
      background: '#ffffff',
      primaryContainercolor: '#ffffff',
      secondaryContainercolor: '#faf5ff',
      textColor: '#1e1b4b',
      textSecondaryColor: '#4338ca',
      labelColor: '#3730a3',
      labelSecondaryColor: '#6d28d9',
      borderColor: '#ddd6fe',
      accent: '#7c3aed',
      accentForeground: '#ffffff',
      successColor: '#10b981',
      warningColor: '#f59e0b',
      errorColor: '#ef4444',
      infoColor: '#3b82f6',
      shadowColor: '124, 58, 237',     // ← R, G, B values only (no #)
      shadowColorOpacity: '0.3',
    },

    // ── Override built-in size/spacing tokens ──────────────
    sizes: {
      radiusMd: '10px',
      fontSizeMd: '15px',
      spacingMd: '18px',
    },

    // ── Your own custom tokens (any name you want!) ────────
    custom: {
      heroBackground: '#f5f3ff',
      heroText: '#4c1d95',
      cardAccent: '#7c3aed',
      sidebarWidth: '260px',
      sidebarBg: '#faf5ff',
      chartColor1: '#7c3aed',
      chartColor2: '#2563eb',
      chartColor3: '#059669',
      navbarHeight: '64px',
      bannerGradient: 'linear-gradient(135deg, #7c3aed, #2563eb)',
    },
  },

  dark: {

    // ── Dark built-in color overrides ─────────────────────
    colors: {
      primaryColor: '#a78bfa',
      lightPrimaryColor: '#2e1065',
      background: '#0f0a1e',
      primaryContainercolor: '#1e1b4b',
      secondaryContainercolor: '#12104c',
      textColor: '#f5f3ff',
      textSecondaryColor: '#c4b5fd',
      labelColor: '#ede9fe',
      labelSecondaryColor: '#a78bfa',
      borderColor: '#4c1d95',
      accent: '#a78bfa',
      accentForeground: '#0f0a1e',
      shadowColor: '167, 139, 250',
      shadowColorOpacity: '0.4',
    },

    // ── Dark custom token overrides ─────────────────────────
    // Only override what changes — anything not listed here
    // falls back to the value defined in light.custom
    custom: {
      heroBackground: '#1e1b4b',
      heroText: '#e9d5ff',
      cardAccent: '#a78bfa',
      sidebarBg: '#12104c',
      chartColor1: '#a78bfa',
      bannerGradient: 'linear-gradient(135deg, #a78bfa, #60a5fa)',
    },
  },
};

Step 3 — Pass it into ThemeProvider

<ThemeProvider theme={myTheme} defaultThemeMode="light">
  <App />
</ThemeProvider>

That's it. All your tokens are now available everywhere.

Step 4 — Use tokens in components

Use the useTheme hook to read any token in your JSX:

import { useTheme } from 'mango-ui-kit';

const HeroSection = () => {
  const {
    themeMode,          // 'light' | 'dark'
    toggleTheme,        // flips mode
    setThemeMode,       // sets specific mode
    colors,             // built-in color tokens
    sizes,              // built-in size tokens
    custom,             // your custom tokens
    tokens,             // ✅ all merged: colors + sizes + custom
  } = useTheme();

  return (
    <div style={{
      background: tokens.heroBackground,       // your custom token
      minHeight: tokens.navbarHeight,          // your custom token
      color: tokens.textColor,                 // built-in token
      borderRadius: tokens.radiusMd,           // built-in size token
      padding: tokens.spacingLg,              // built-in size token
    }}>
      <h1 style={{ color: tokens.heroText }}>
        Welcome!
      </h1>

      <div style={{
        background: tokens.bannerGradient,     // custom gradient string
        borderColor: tokens.accent,
      }}>
        Call to Action
      </div>

      {/* Toggle dark/light */}
      <button onClick={toggleTheme}>
        {themeMode === 'light' ? '🌙 Dark Mode' : '☀️ Light Mode'}
      </button>
    </div>
  );
};

useTheme Return Values:

Step 5 — Auto-injected CSS variables

Every token is automatically injected as a CSS variable on <html> whenever the theme changes. You can use them anywhere in your CSS files.

Built-in color variables:

.my-card {
  background: var(--primaryContainercolor);
  color: var(--textColor);
  border: 1px solid var(--borderColor);
  box-shadow: 0 4px 20px rgba(var(--shadowColorRGB), var(--shadowOpacity));
}

Built-in size variables:

.my-card {
  border-radius: var(--radius-md);
  font-size: var(--font-size-md);
  padding: var(--spacing-md);
}

Your custom tokens (auto-prefixed with `--custom-`):

Your camelCase key names are auto-converted to kebab-case:

/* These switch between light and dark values automatically! */
.hero {
  background: var(--custom-hero-background);
  color: var(--custom-hero-text);
}

.sidebar {
  width: var(--custom-sidebar-width);
  background: var(--custom-sidebar-bg);
}

.chart-bar-1 { fill: var(--custom-chart-color1); }
.chart-bar-2 { fill: var(--custom-chart-color2); }

Built-in Color Tokens Reference

All 19 built-in color tokens with their CSS variable names and defaults:

Built-in Size Tokens Reference

All 13 built-in size/spacing tokens. These also switch per theme mode if you override them:

🍱 Essential Components

🔘 Button

import { Button } from 'mango-ui-kit';

<Button variant="primary" size="md">Solid Button</Button>
<Button variant="outline">Outline</Button>
<Button variant="soft" loading>Saving...</Button>
<Button variant="ghost">Ghost</Button>

🔽 Dropdown

import { Dropdown } from 'mango-ui-kit';

<Dropdown
  trigger={<Button>Options</Button>}
  items={[
    { id: 'edit', label: 'Edit Profile', onClick: () => {} },
    { id: 'settings', label: 'Settings', divider: true },
    { id: 'logout', label: 'Logout', color: 'error' },
  ]}
/>

📝 Input & Checkbox

import { Input, Checkbox } from 'mango-ui-kit';

<Input label="Email" placeholder="[email protected]" required />
<Checkbox label="I agree to the terms" variant="soft" />

🖼️ Modal

import { Modal, Button } from 'mango-ui-kit';
import { useState } from 'react';

const [isOpen, setIsOpen] = useState(false);

<Modal isOpen={isOpen} onClose={() => setIsOpen(false)} title="Confirm">
  <p>Are you sure you want to continue?</p>
  <div style={{ display: 'flex', gap: '8px', marginTop: '16px', justifyContent: 'flex-end' }}>
    <Button variant="ghost" onClick={() => setIsOpen(false)}>Cancel</Button>
    <Button variant="primary">Confirm</Button>
  </div>
</Modal>

📊 Stat Card

import { StatCard } from 'mango-ui-kit';

<StatCard
  title="Total Revenue"
  value="$48,295"
  change={+12.4}
  icon={<DollarSign />}
/>

📄 Table

import { Table } from 'mango-ui-kit';

<Table
  columns={[
    { key: 'name', title: 'Name' },
    { key: 'status', title: 'Status' },
    { key: 'amount', title: 'Amount' },
  ]}
  data={rows}
/>

🗂️ Tabs

import { Tabs } from 'mango-ui-kit';

<Tabs
  tabs={[
    { id: 'overview', label: 'Overview', content: <OverviewPanel /> },
    { id: 'analytics', label: 'Analytics', content: <AnalyticsPanel /> },
    { id: 'settings', label: 'Settings', content: <SettingsPanel /> },
  ]}
/>

✨ Advanced Features

🍞 Toast Notifications

import { toast, ToastContainer } from 'mango-ui-kit';

// 1. Add the container once at root level
<ToastContainer position="top-right" />

// 2. Fire toasts from anywhere
toast.success('Saved successfully!');
toast.error('Something went wrong', { duration: 5000 });
toast.warning('Please review your input');
toast.info('New update available');

🔍 Command Palette (⌘K)

import { CommandPalette } from 'mango-ui-kit';

<CommandPalette
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  actions={[
    { id: 'search', label: 'Search Projects', section: 'Quick Links', shortcut: 'P' },
    { id: 'settings', label: 'Global Settings', section: 'System' },
    { id: 'logout', label: 'Sign Out', section: 'Account' },
  ]}
  onAction={(action) => router.push(`/${action.id}`)}
/>

📤 Media Uploader

import { MediaUploader } from 'mango-ui-kit';

<MediaUploader
  multiple
  maxSize={5}        // MB
  accept="image/*"
  onFilesAdded={(files) => handleUpload(files)}
/>

📅 Calendar & Date Picker

import { CalendarDatePicker } from 'mango-ui-kit';

<CalendarDatePicker
  value={selectedDate}
  onChange={(date) => setSelectedDate(date)}
  placeholder="Pick a date"
/>

🔢 OTP Input

import { OtpInput } from 'mango-ui-kit';

<OtpInput
  length={6}
  onComplete={(code) => verifyOtp(code)}
/>

🛶 Layout System

Build complex, responsive grid layouts using Box, Row, Column, and Col. Inspired by Flutter's layout model.

import { Row, Column, Col, Box } from 'mango-ui-kit';

<Row mainAxisAlignment="spaceBetween" crossAxisAlignment="center" gap="20px">
  <Col span={{ xs: 12, md: 8 }}>
    <Box bg="var(--primaryContainercolor)" shadow="lg" p="40px" radius="20px">
      Main Content
    </Box>
  </Col>
  <Col span={{ xs: 12, md: 4 }}>
    <Column gap="12px">
      <Box bg="var(--secondaryContainercolor)" p="20px" radius="12px">Side Top</Box>
      <Box bg="var(--secondaryContainercolor)" p="20px" radius="12px">Side Bottom</Box>
    </Column>
  </Col>
</Row>

Box Props (shorthand style system):

🛡️ TypeScript Support

Mango UI Kit is written in TypeScript from the ground up. Import any type you need:

import type {
  ButtonProps,
  ThemeConfig,
  ThemeColors,
  ThemeSizes,
  CustomTokens,
  ThemeMode,
  BoxProps,
  RowProps,
  ColProps,
} from 'mango-ui-kit';

🤝 Contributing & Support

Found a bug? → Open an issue
Want to contribute? → Submit a Pull Request
Need help? → DM on Twitter @nitishroy

To run locally:

git clone https://github.com/Nitishroy-7033/Mango-Ui-Kit
cd Mango-Ui-Kit
npm install
npm run storybook