🎯 @ribinmathew/status-chip

A lightweight, customizable Status Chip component for React + TypeScript + Tailwind CSS projects.

🔥 Overview

@ribinmathew/status-chip provides a simple and flexible StatusChip component perfect for dashboards, admin panels, healthcare apps (such as e-Medicos), workflow UIs, and more.

The component is designed to integrate seamlessly with:

• Next.js
• React
• Tailwind CSS
• TypeScript

You can style it using Tailwind, use custom icons, and integrate into any UI structure.

✨ Features

• 🚀 Extremely lightweight (under 3KB)
• 🎨 Tailwind CSS-based styling
• ⚛ Written in TypeScript with full typings
• 🎯 Works with shadcn/ui or plain React
• 🔄 Supports 10+ medical workflow statuses
• 🔧 Allows custom icons using lucide-react or any icons
• 📦 ESM + CJS output for broad compatibility
• 🌙 Supports dark mode themes

📦 Installation

Install with npm:

npm install @ribinmathew/status-chip

Or with yarn:

yarn add @ribinmathew/status-chip

Or with pnpm:

pnpm add @ribinmathew/status-chip

🚀 Quick Start

"use client";
import { StatusChip } from "@ribinmathew/status-chip";

export default function App() {
  return (
    <div>
      <StatusChip status="success" />
    </div>
  );
}

📖 How to Use

Basic Usage

The simplest way to use the StatusChip component is to import it and pass a status prop:

"use client";
import { StatusChip } from "@ribinmathew/status-chip";

export default function Demo() {
  return (
    <div className="p-6 space-y-3">
      <StatusChip status="pending" />
      <StatusChip status="success" />
      <StatusChip status="failed" />
      <StatusChip status="acknowledged" />
      <StatusChip status="completed" />
    </div>
  );
}

Custom Icons

You can override the default icon by passing a custom icon component:

"use client";
import { StatusChip } from "@ribinmathew/status-chip";
import { CheckCircle } from "lucide-react";

export default function Page() {
  return (
    <div className="p-6">
      <StatusChip
        status="success"
        icon={<CheckCircle className="w-3 h-3" />}
      />
    </div>
  );
}

Dynamic Status

Use conditional logic to display status based on your data:

<StatusChip status={payment.status === 1 ? "success" : "failed"} />

Example with API Data

"use client";
import { StatusChip } from "@ribinmathew/status-chip";

interface Order {
  id: string;
  status: number;
}

export default function OrderList({ orders }: { orders: Order[] }) {
  const getOrderStatus = (statusCode: number) => {
    switch (statusCode) {
      case 0: return "pending";
      case 1: return "success";
      case 2: return "failed";
      case 3: return "cancelled";
      default: return "pending";
    }
  };

  return (
    <div className="space-y-2">
      {orders.map((order) => (
        <div key={order.id} className="flex items-center gap-3">
          <span>Order #{order.id}</span>
          <StatusChip status={getOrderStatus(order.status)} />
        </div>
      ))}
    </div>
  );
}

📊 Available Statuses

The component supports the following status values:

| Status | Description | Color | |--------|-------------|-------| | pending | Awaiting action or processing | Yellow | | success | Completed successfully | Green | | failed | Operation failed | Red | | error | System error occurred | Red | | warning | Needs attention | Orange | | info | Informational status | Blue | | acknowledged | Received and noted | Purple | | completed | Task finished | Green | | cancelled | Operation cancelled | Gray | | in-progress | Currently processing | Blue |

🔧 API Reference

Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | status | string | Yes | - | The status type to display | | icon | ReactNode | No | Auto | Custom icon component | | className | string | No | - | Additional CSS classes |

Usage Example

<StatusChip 
  status="success" 
  icon={<CheckIcon />}
  className="my-custom-class"
/>

💡 Integration Examples

With Data Tables

import { StatusChip } from "@ribinmathew/status-chip";

const columns = [
  {
    accessorKey: "status",
    header: "Status",
    cell: ({ row }) => (
      <StatusChip status={row.getValue("status")} />
    ),
  },
  // ... other columns
];

With Forms

import { StatusChip } from "@ribinmathew/status-chip";
import { useState } from "react";

export default function FormWithStatus() {
  const [submitStatus, setSubmitStatus] = useState<"pending" | "success" | "failed">("pending");

  const handleSubmit = async () => {
    setSubmitStatus("pending");
    try {
      await submitForm();
      setSubmitStatus("success");
    } catch (error) {
      setSubmitStatus("failed");
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      {/* form fields */}
      <div className="flex items-center gap-2">
        <button type="submit">Submit</button>
        <StatusChip status={submitStatus} />
      </div>
    </form>
  );
}

With shadcn/ui Cards

import { StatusChip } from "@ribinmathew/status-chip";
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";

export default function Dashboard() {
  return (
    <Card>
      <CardHeader>
        <div className="flex items-center justify-between">
          <CardTitle>Recent Transactions</CardTitle>
          <StatusChip status="success" />
        </div>
      </CardHeader>
      <CardContent>
        {/* content */}
      </CardContent>
    </Card>
  );
}

🎨 Styling & Customization

The component uses Tailwind CSS utility classes. You can wrap it in a container with custom classes:

<div className="flex items-center gap-2 p-4 rounded-lg bg-gray-50 dark:bg-gray-900">
  <span className="text-sm font-medium">Payment Status:</span>
  <StatusChip status="success" />
</div>

📘 TypeScript Support

The component is fully typed. Import types if needed:

import { StatusChip } from "@ribinmathew/status-chip";
import type { StatusChipProps } from "@ribinmathew/status-chip";

const MyComponent = ({ status }: { status: StatusChipProps["status"] }) => {
  return <StatusChip status={status} />;
};

⚡ Next.js App Router

For Next.js 13+ with App Router, use the "use client" directive:

"use client";
import { StatusChip } from "@ribinmathew/status-chip";

export default function Page() {
  return <StatusChip status="success" />;
}

🔄 Common Patterns

Loading States

const [isLoading, setIsLoading] = useState(false);

<StatusChip status={isLoading ? "in-progress" : "completed"} />

Multi-step Workflows

const steps = [
  { id: 1, name: "Submitted", status: "completed" },
  { id: 2, name: "Under Review", status: "in-progress" },
  { id: 3, name: "Approved", status: "pending" },
];

return (
  <div className="space-y-2">
    {steps.map((step) => (
      <div key={step.id} className="flex items-center gap-3">
        <span>{step.name}</span>
        <StatusChip status={step.status} />
      </div>
    ))}
  </div>
);

🛠️ Requirements

• React 16.8+
• Tailwind CSS 3.0+
• TypeScript 4.0+ (optional)

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

📝 License

MIT © [Ribin Mathew]

🔗 Links

• NPM Package
• Report Issues

💖 Support

If you find this package helpful, please consider:

• ⭐ Starring the repository
• 🐛 Reporting bugs
• 💡 Suggesting new features
• 📢 Sharing with others

Made with ❤️ by [Ribin Mathew]