@shared-cms/badge
v1.0.13
Published
A reusable badge component built with Lit, TypeScript, and TailwindCSS. Perfect for notifications, status indicators, and tags.
Maintainers
difadevReadme
@shared-cms/badge
A reusable badge component built with Lit, TypeScript, and TailwindCSS. Perfect for notifications, status indicators, tags, and labels.
✨ Features
- 🏷️ Multiple Variants - Primary, secondary, success, warning, danger, info, and outline styles
- 📏 Flexible Sizes - Small, medium, and large options for different use cases
- 🔢 Count Display - Perfect for notifications and numeric indicators
- 🔵 Dot Indicators - Status dots for online presence and activity states
- 🗑️ Removable - Built-in remove functionality with custom events
- 🚀 Framework Agnostic - Works with React, Angular, Vue, and vanilla JavaScript
- 📱 Responsive Design - Mobile-first, accessible badge component
- 🌙 Shadow DOM - Complete style isolation, no CSS conflicts
- 📦 Lightweight - Optimized bundle size with minimal dependencies
- 🔧 TypeScript - Full TypeScript support with comprehensive type definitions
- ♿ Accessible - WCAG compliant with proper ARIA attributes
- 🎯 Custom Events - Emits standard and custom events for easy integration
📦 Installation
npm install @shared-cms/badge
# or
yarn add @shared-cms/badge
# or
pnpm add @shared-cms/badge🚀 Quick Start
HTML/Vanilla JavaScript
<!DOCTYPE html>
<html>
<head>
<script type="module" src="node_modules/@shared-cms/badge/dist/shared-badge.es.js"></script>
</head>
<body>
<shared-badge label="Primary" variant="primary"></shared-badge>
<shared-badge count={5} variant="danger"></shared-badge>
<shared-badge dot variant="success"></shared-badge>
<shared-badge label="Removable" variant="secondary" removable></shared-badge>
<script>
// Listen to custom events
document.querySelector('shared-badge').addEventListener('badge-click', (e) => {
console.log('Badge clicked!', e.detail);
});
document.querySelector('shared-badge[removable]').addEventListener('badge-remove', (e) => {
console.log('Badge removed!', e.detail);
});
</script>
</body>
</html>React
Natural React Component Usage
// Import as default export - most natural for React users
import SharedBadge from '@shared-cms/badge';
function App() {
const handleRemove = (badge) => {
console.log('Removing badge:', badge.detail);
};
return (
<div>
<SharedBadge label="React" variant="primary" />
<SharedBadge count={12} variant="danger" removable onBadgeRemove={handleRemove} />
<SharedBadge dot variant="success" />
<SharedBadge
label="Click me"
variant="secondary"
onClick={() => console.log('badge clicked')}
/>
</div>
);
}
export default App;Advanced Usage with TypeScript
import SharedBadge, { SharedBadgeProps, SharedBadgeElement } from '@shared-cms/badge';
import { useRef, useCallback } from 'react';
function AdvancedExample() {
const badgeRef = useRef<SharedBadgeElement>(null);
const handleClick = useCallback((event: React.MouseEvent) => {
console.log('React onClick triggered!', event);
badgeRef.current?.focus();
}, []);
const handleBadgeClick = useCallback((event: CustomEvent) => {
console.log('Custom badge-click event!', event.detail);
}, []);
const handleRemove = useCallback((event: CustomEvent) => {
console.log('Badge removed!', event.detail);
// Remove from UI or update state
}, []);
return (
<SharedBadge
ref={badgeRef}
label="Advanced Badge"
variant="primary"
onClick={handleClick}
onBadgeClick={handleBadgeClick}
onBadgeRemove={handleRemove}
removable
id="my-badge"
aria-label="Status badge"
/>
);
}Different Import Options
// Option 1: Default export (recommended for React)
import SharedBadge from '@shared-cms/badge';
// Option 2: Named export
import { ReactSharedBadge } from '@shared-cms/badge';
// Usage: <ReactSharedBadge />
// Option 3: With types
import SharedBadge, { SharedBadgeProps } from '@shared-cms/badge';
// Option 4: For vanilla JS usage
import { LitBadge } from '@shared-cms/badge';🎨 API Reference
Properties
| Property | Type | Default | Description |
|----------|------|---------|-------------|
| label | string | "" | Badge text/content |
| variant | "primary" \| "secondary" \| "success" \| "warning" \| "danger" \| "info" \| "outline" | "primary" | Badge style variant |
| size | "small" \| "medium" \| "large" | "medium" | Badge size |
| count | number \| null | null | Numeric count for notifications |
| removable | boolean | false | Whether badge shows remove button |
| dot | boolean | false | Show as dot indicator |
| disabled | boolean | false | Whether badge is disabled |
Events
| Event | Type | Description |
|-------|------|-------------|
| badge-click | CustomEvent | Fired when badge is clicked |
| badge-remove | CustomEvent | Fired when remove button is clicked |
| click | Event | Standard DOM click event |
Styling
The component uses TailwindCSS classes internally within Shadow DOM:
/* Primary variant */
.badge-primary {
@apply bg-blue-600 text-white rounded-full font-medium;
}
/* Count indicator */
.badge-count {
@apply bg-red-500 text-white text-xs font-bold rounded-full;
}
/* Dot indicator */
.badge-dot {
@apply w-2 h-2 rounded-full;
}
/* Removable badge */
.badge-remove {
@apply ml-1 text-gray-400 hover:text-gray-600 cursor-pointer;
}🎯 Usage Examples
Basic Badges
<SharedBadge label="Primary" variant="primary" />
<SharedBadge label="Success" variant="success" />
<SharedBadge label="Warning" variant="warning" />
<SharedBadge label="Danger" variant="danger" />Count Badges
<SharedBadge count={5} variant="danger" />
<SharedBadge count={12} variant="info" />
<SharedBadge count={99} variant="warning" />Dot Indicators
<SharedBadge dot variant="success" /> {/* Online */}
<SharedBadge dot variant="warning" /> {/* Away */}
<SharedBadge dot variant="secondary" /> {/* Offline */}Removable Badges
const [tags, setTags] = useState(['React', 'TypeScript', 'Lit']);
return (
<div>
{tags.map((tag, index) => (
<SharedBadge
key={index}
label={tag}
variant="primary"
removable
onBadgeRemove={(e) => {
setTags(prev => prev.filter((_, i) => i !== index));
}}
/>
))}
</div>
);Size Variations
<SharedBadge label="Small" size="small" variant="primary" />
<SharedBadge label="Medium" size="medium" variant="primary" />
<SharedBadge label="Large" size="large" variant="primary" />🔧 Development
# Install dependencies
npm install
# Start development server
npm run serve
# Build for production
npm run build
# Build and watch for changes
npm run dev📁 Project Structure
packages/badge/
├── src/
│ ├── Badge.ts # Main Lit component
│ ├── react-wrapper.tsx # React wrapper
│ ├── Badge.module.scss # Component styles
│ ├── index.ts # Exports
│ └── styles/
│ └── tailwind.css # TailwindCSS base styles
├── dist/
│ ├── shared-badge.es.js # ES Module build
│ ├── shared-badge.umd.js # UMD build
│ └── index.d.ts # TypeScript definitions
├── package.json
├── README.md
├── LICENSE
└── vite.config.ts🌟 Browser Support
- Chrome 54+
- Firefox 63+
- Safari 10.1+
- Edge 79+
📄 License
MIT License - see LICENSE file for details
🔗 Related Packages
@shared-cms/button- Button component@shared-cms/card- Card component@shared-cms/input- Input component@shared-cms/modal- Modal component
📞 Support
For support, questions, or contributions, please visit our GitHub repository or contact us at [email protected].