@versini/ui-pill

A versatile and accessible React pill component built with TypeScript and TailwindCSS.

The Pill component provides status indicators, badges, and labels with multiple variants and built-in accessibility features. Perfect for displaying statuses, categories, or other categorical information.

Table of Contents

• Features
• Installation
• Usage

Features

• 🎯 Multiple Variants: Information, warning, error, and success styles
• ♿ Accessible: Built-in screen reader support with optional descriptions
• 🎨 Customizable: Easy to style and integrate with your design system
• 🌲 Tree-shakeable: Lightweight and optimized for bundle size
• 🔧 TypeScript: Fully typed with comprehensive prop definitions
• 📱 Responsive: Works seamlessly across all device sizes

Installation

npm install @versini/ui-pill

Note: This component requires TailwindCSS and the @versini/ui-styles plugin for proper styling. See the installation documentation for complete setup instructions.

Usage

Basic Pill

import { Pill } from "@versini/ui-pill";

function App() {
  return <Pill label="Active" />;
}

Different Variants

import { Pill } from "@versini/ui-pill";

function App() {
  return (
    <div className="space-x-2">
      <Pill label="Information" variant="information" />
      <Pill label="Success" variant="success" />
      <Pill label="Warning" variant="warning" />
      <Pill label="Error" variant="error" />
    </div>
  );
}

Accessible Pills with Descriptions

import { Pill } from "@versini/ui-pill";

function App() {
  return (
    <div className="space-x-2">
      <Pill label="Online" variant="success" description="User status" />
      <Pill label="Pending" variant="warning" description="Order status" />
      <Pill label="Failed" variant="error" description="Deployment status" />
    </div>
  );
}

API

Pill Props

| Prop | Type | Default | Description | | ----------- | ---------------------------------------------------- | --------------- | ------------------------------------------------------- | | label | string | - | Content of the Pill (required) | | variant | "information" \| "warning" \| "error" \| "success" | "information" | Theme of the Pill | | description | string | - | Hidden label for screen readers (2-3 words recommended) | | className | string | - | CSS class(es) to add to the main component wrapper |

Examples

Status Indicators

import { Pill } from "@versini/ui-pill";

function StatusIndicators() {
  const users = [
    { name: "Alice", status: "online" },
    { name: "Bob", status: "away" },
    { name: "Charlie", status: "offline" }
  ];

  const getStatusVariant = (status: string) => {
    switch (status) {
      case "online":
        return "success";
      case "away":
        return "warning";
      case "offline":
        return "error";
      default:
        return "information";
    }
  };

  return (
    <div className="space-y-2">
      {users.map((user) => (
        <div key={user.name} className="flex items-center space-x-2">
          <span>{user.name}</span>
          <Pill
            label={user.status}
            variant={getStatusVariant(user.status)}
            description="User status"
          />
        </div>
      ))}
    </div>
  );
}

Order Status Dashboard

import { Pill } from "@versini/ui-pill";

function OrderDashboard() {
  const orders = [
    { id: "ORD-001", status: "processing", variant: "information" },
    { id: "ORD-002", status: "shipped", variant: "success" },
    { id: "ORD-003", status: "delayed", variant: "warning" },
    { id: "ORD-004", status: "cancelled", variant: "error" }
  ];

  return (
    <div className="space-y-3">
      <h3>Recent Orders</h3>
      {orders.map((order) => (
        <div
          key={order.id}
          className="flex justify-between items-center p-3 border rounded"
        >
          <span className="font-mono">{order.id}</span>
          <Pill
            label={order.status}
            variant={order.variant as any}
            description="Order status"
          />
        </div>
      ))}
    </div>
  );
}

Category Tags

import { Pill } from "@versini/ui-pill";

function CategoryTags() {
  const article = {
    title: "Getting Started with React",
    categories: ["Frontend", "JavaScript", "React", "Tutorial"]
  };

  return (
    <div className="space-y-3">
      <h2>{article.title}</h2>
      <div className="flex flex-wrap gap-2">
        {article.categories.map((category) => (
          <Pill
            key={category}
            label={category}
            variant="information"
            description="Article category"
          />
        ))}
      </div>
    </div>
  );
}

Custom Styled Pills

import { Pill } from "@versini/ui-pill";

function CustomStyledPills() {
  return (
    <div className="space-y-4">
      <div className="space-x-2">
        <Pill
          label="Premium"
          variant="success"
          className="font-bold border-2 border-gold-500"
        />
        <Pill label="Beta" variant="information" className="animate-pulse" />
      </div>

      <div className="space-x-2">
        <Pill label="Large" className="px-4 py-2 text-lg" />
        <Pill label="Small" className="px-1 py-0.5 text-xs" />
      </div>
    </div>
  );
}

Notification Badges

import { Pill } from "@versini/ui-pill";

function NotificationBadges() {
  return (
    <div className="space-y-4">
      <div className="relative inline-block">
        <button className="p-2 bg-gray-200 rounded">Messages</button>
        <Pill
          label="3"
          variant="error"
          description="Unread messages"
          className="absolute -top-2 -right-2 min-w-[20px] h-5 text-xs"
        />
      </div>

      <div className="relative inline-block">
        <button className="p-2 bg-gray-200 rounded">Notifications</button>
        <Pill
          label="!"
          variant="warning"
          description="New notifications"
          className="absolute -top-1 -right-1 w-4 h-4 text-xs flex items-center justify-center"
        />
      </div>
    </div>
  );
}