Zango Components

A modern React component library built with Tailwind CSS and customizable CSS variables that inherit from parent applications. Perfect for building consistent, accessible UI components across your applications.

🚀 Features

• Tailwind CSS Integration: All components use Tailwind utility classes for consistent styling
• Color Inheritance: CSS variables allow parent applications to override colors
• TypeScript Support: Full type definitions for all components
• Responsive Design: Components adapt to different screen sizes
• Accessibility: Proper ARIA attributes and keyboard navigation
• Storybook Documentation: Interactive component documentation

📦 Installation

npm install @zango/components

🎨 Setup

Peer Dependencies

Make sure you have the following peer dependencies installed:

npm install react react-dom @radix-ui/react-dialog lucide-react

Optional: Tailwind CSS Integration

If your project uses Tailwind CSS, you can optionally add the library to your content scanning for better integration:

// tailwind.config.js
module.exports = {
  content: [
    "./src/**/*.{js,jsx,ts,tsx}",
    "./node_modules/@zango/components/dist/**/*.{js,jsx,ts,tsx}", // Optional: for better integration
  ],
  theme: {
    extend: {
      // You can extend or override colors here
    },
  },
  plugins: [],
}

Note: This step is optional. The library works perfectly without any Tailwind configuration in your project.

🎯 Usage

Basic Usage

import { Button, Badge, Accordion } from '@zango/components';
// CSS is automatically included - no separate import needed!

function App() {
  return (
    <div className="p-4">
      <Button variant="primary" size="medium">
        Click me
      </Button>
      
      <Badge variant="success">Active</Badge>
      
      <Accordion
        items={[
          {
            key: "item1",
            title: "Accordion Item",
            content: "This is the content"
          }
        ]}
      />
    </div>
  );
}

With Custom Colors

/* Override colors in your CSS */
:root {
  --color-Brand-500: #3b82f6;
  --color-Brand-600: #2563eb;
  --color-Brand-700: #1d4ed8;
}

// Components will automatically use your custom colors
<Button variant="primary">Custom Colored Button</Button>

🧩 Available Components

Button

A versatile button component with multiple variants and sizes.

<Button 
  variant="primary" 
  size="medium" 
  fullWidth={false}
  disabled={false}
>
  Button Text
</Button>

Props:

• variant: 'primary' | 'secondary' | 'ghost' | 'outline' | 'destructive' | 'danger' | 'success'
• size: 'small' | 'medium' | 'large' | 'sm' | 'md' | 'lg'
• fullWidth: boolean
• All standard HTML button attributes

Badge

Status indicators with multiple variants.

<Badge variant="success">Success</Badge>
<Badge variant="warning">Warning</Badge>
<Badge variant="danger">Error</Badge>

Props:

• variant: 'success' | 'low' | 'warning' | 'medium' | 'danger' | 'high' | 'critical' | 'neutral' | 'default' | 'outline'

Accordion

Expandable content sections with smooth animations.

<Accordion
  items={[
    {
      key: "item1",
      title: "First Item",
      content: <p>Content goes here</p>,
      icon: <IconComponent />,
      subtitle: "Optional subtitle"
    }
  ]}
  multiple={true}
  collapsible={true}
/>

Context Menu

Dropdown menus with customizable items.

<ContextMenu
  trigger={<Button>Open Menu</Button>}
  align="right"
>
  <ContextMenuItem onClick={() => console.log('clicked')}>
    Menu Item
  </ContextMenuItem>
  <ContextMenuSeparator />
  <ContextMenuItem danger>Delete</ContextMenuItem>
</ContextMenu>

Info Section

Flexible information display with multiple layouts.

<InfoSection
  title="Section Title"
  subtitle="Subtitle"
  description="Description text"
  variant="card"
  size="medium"
  icon={<IconComponent />}
  badge={<Badge variant="success">New</Badge>}
  actions={<Button size="small">Edit</Button>}
>
  <InfoGrid columns={2}>
    <InfoItem label="Label" value="Value" />
    <InfoItem label="Status" value="Active" />
  </InfoGrid>
</InfoSection>

Timeline

Event timeline with date grouping.

<Timeline
  sections={[
    {
      date: "Today",
      events: [
        {
          id: "1",
          type: "status_change",
          title: "Status Updated",
          description: "Changed to active",
          timestamp: "2:30 PM",
          date: "Dec 15",
          icon: "activity"
        }
      ]
    }
  ]}
/>

Drawer

Sliding panel overlay for displaying additional content.

<Drawer
  open={open}
  onClose={() => setOpen(false)}
  title="Drawer Title"
  size="md"
  position="right"
>
  <p>Drawer content</p>
</Drawer>

Props:

• open: boolean (required)
• onClose: () => void (required)
• size: 'sm' | 'md' | 'lg' | 'xl' | 'full'
• position: 'right' | 'left' | 'top' | 'bottom'
• title: string
• showBackButton: boolean
• onBack: () => void

Full Drawer documentation →

Toast

Beautiful toast notifications powered by Sonner with customizable variants, positions, and actions.

import { Toaster, toast, useToast } from '@zango/components';

// Add Toaster to your app root
function App() {
  return (
    <>
      <YourApp />
      <Toaster position="top-right" />
    </>
  );
}

// Use toast in your components
function MyComponent() {
  const { success, error, warning, info } = useToast();

  return (
    <Button onClick={() => success('Operation successful!')}>
      Show Toast
    </Button>
  );
}

Toast Options:

toast.success({
  title: 'Success toast message',
  description: 'Optional description text',
  duration: 5000,
  icon: <CustomIcon />,
  primaryAction: {
    label: 'Undo',
    onClick: () => console.log('Undo clicked')
  },
  secondaryAction: {
    label: 'Dismiss',
    onClick: () => console.log('Dismissed')
  }
});

Props:

• position: 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'
• duration: number (milliseconds)
• variant: 'success' | 'error' | 'warning' | 'info' | 'default'
• Custom icons and actions supported

🎨 Customizing Colors

The component library uses CSS variables that can be overridden in your application:

:root {
  /* Brand colors */
  --color-Brand-500: #your-primary-color;
  --color-Brand-600: #your-primary-hover;
  --color-Brand-700: #your-primary-active;
  
  /* Gray colors */
  --color-Gray-100: #your-gray-light;
  --color-Gray-500: #your-gray-medium;
  --color-Gray-900: #your-gray-dark;
  
  /* Status colors */
  --color-success-500: #your-success-color;
  --color-error-500: #your-error-color;
  --color-warning-500: #your-warning-color;
  
  /* Base colors */
  --color-Base-white: #ffffff;
  --color-Base-black: #000000;
}

🛠️ Development

Prerequisites

• Node.js (v16 or later)
• npm or yarn

Getting Started

# Clone the repository
git clone https://github.com/yourusername/zango-react-components.git
cd zango-react-components

# Install dependencies
npm install

# Start development server
npm run dev

# Run Storybook for component development
npm run storybook

# Build the library
npm run build

# Type check
npm run type-check

# Lint code
npm run lint

Project Structure

src/
├── components/          # Component source files
│   ├── Button/
│   ├── Badge/
│   ├── Accordion/
│   ├── ContextMenu/
│   ├── InfoSection/
│   ├── Timeline/
│   └── Drawer/
├── styles/
│   ├── index.css       # Main Tailwind CSS file
│   └── variables.css   # CSS variables
├── utils/
│   └── cn.ts          # Class name utility
└── index.ts           # Main export file

Available Scripts

• npm run dev - Start development server
• npm run build - Build the library for production
• npm run storybook - Start Storybook development server
• npm run build-storybook - Build Storybook for production
• npm run type-check - Run TypeScript type checking
• npm run lint - Run ESLint

Building for Production

npm run build

This creates a dist folder with:

• zango-components.js - ES module build (with CSS included)
• zango-components.umd.cjs - UMD build (with CSS included)
• Type definitions

📚 Documentation

Visit our Storybook documentation to see all components in action with interactive examples.

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

MIT License - see the LICENSE file for details.

🆘 Support

If you encounter any issues or have questions:

1. Check the Storybook documentation
2. Search existing issues
3. Create a new issue if needed

Made with ❤️ using React, TypeScript, and Tailwind CSS