tinky-badge

A React-like badge component library for building beautiful terminal UIs.

tinky-badge provides a fully-featured badge component for terminal applications built with the tinky framework. It supports customizable colors, automatic text transformation, and seamless theme integration.

Features

• 📝 Simple API - Intuitive JSX-based syntax for creating badges
• 🎨 Themeable - Full integration with tinky-theme
• 🎯 Customizable Colors - Support for all standard terminal colors
• 🔤 Auto Uppercase - String content is automatically converted to uppercase
• 🎨 High Contrast - Black text on colored backgrounds for readability
• 🎯 Type Safe - Built with TypeScript for excellent developer experience
• 🧪 Well Tested - Comprehensive test coverage with unit tests
• 📚 Documented - Complete API documentation generated with TypeDoc

Installation

npm install tinky-badge

# or

bun add tinky-badge

# or

yarn add tinky-badge

Quick Start

import { render } from "tinky";
import { Badge } from "tinky-badge";

function App() {
  return (
    <>
      <Badge color="green">Success</Badge>
      <Badge color="red">Error</Badge>
      <Badge color="blue">Info</Badge>
    </>
  );
}

render(<App />);

Usage

Basic Badge

Create a simple colored badge:

import { Badge } from "tinky-badge";

// Default magenta color
<Badge>Default</Badge>

// Custom colors
<Badge color="green">Success</Badge>
<Badge color="red">Error</Badge>
<Badge color="yellow">Warning</Badge>
<Badge color="blue">Info</Badge>

Color Options

The Badge component supports all standard terminal colors:

| Color | Example | | --------- | -------------------------------------------------- | | black | <Badge color="black">Text</Badge> | | red | <Badge color="red">Error</Badge> | | green | <Badge color="green">Success</Badge> | | yellow | <Badge color="yellow">Warning</Badge> | | blue | <Badge color="blue">Info</Badge> | | magenta | <Badge color="magenta">Default</Badge> (default) | | cyan | <Badge color="cyan">Active</Badge> | | white | <Badge color="white">Text</Badge> | | gray | <Badge color="gray">Disabled</Badge> |

Text Transformation

String children are automatically converted to uppercase:

// Input
<Badge color="green">success</Badge>

// Renders: SUCCESS (in uppercase)

For non-string children (React elements), no transformation is applied:

<Badge color="blue">
  <Text>Status:</Text> Active
</Badge>

API Documentation

For complete API documentation, type definitions, and usage examples, visit the API Docs.

Components

Badge

The badge component for rendering colored labels.

Props:

| Property | Type | Required | Default | Description | | ---------- | -------------------- | -------- | --------- | --------------------------------------------- | | children | ReactNode | Yes | - | Content to display (strings become uppercase) | | color | TextProps['color'] | No | magenta | Background color of the badge |

Example:

<Badge color="green">Success</Badge>

Theme Configuration

badgeTheme

Default theme configuration for the Badge component.

Type: BadgeTheme

Example:

import { useComponentTheme } from "tinky-theme";
import { badgeTheme } from "tinky-badge";

function CustomBadge({ color, children }) {
  const { styles } = useComponentTheme("Badge", badgeTheme, { color });

  return (
    <Box {...styles.container}>
      <Text {...styles.label}>{children}</Text>
    </Box>
  );
}

BadgeTheme

Type definition for the Badge theme configuration.

Example:

import type { BadgeTheme } from "tinky-badge";

const customTheme: BadgeTheme = {
  styles: {
    container: ({ color }) => ({
      backgroundColor: color,
      padding: 1,
    }),
    label: () => ({
      color: "white",
    }),
  },
};

Styling

The Badge component uses a theme-based styling system via tinky-theme.

Style Structure

{
  styles: {
    container: ({ color }) => ({ backgroundColor: color }),
    label: () => ({ color: "black" }),
  }
}

Custom Styling

You can customize the badge appearance by providing a custom theme:

import { useComponentTheme } from "tinky-theme";

const customTheme = {
  styles: {
    container: ({ color }) => ({
      backgroundColor: color,
      padding: 1,
      bold: true,
    }),
    label: () => ({
      color: "white",
      italic: true,
    }),
  },
};

function CustomBadge({ color, children }) {
  const { styles } = useComponentTheme("Badge", customTheme, { color });

  return (
    <Text {...styles.container}>
      {" "}
      <Text {...styles.label}>{children}</Text>
    </Text>
  );
}

Development

Setup

# Install dependencies
bun install

# Run tests
bun test

# Build the project
bun run build

# Lint code
bun run lint

# Generate documentation
bun run docs

Project Structure

tinky-badge/
├── src/
│   ├── components/
│   │   └── badge/
│   │       ├── badge.tsx      # Badge component implementation
│   │       └── index.ts       # Component re-exports
│   ├── themes/
│   │   └── badge-theme.tsx    # Theme configuration
│   └── index.ts               # Package exports
├── tests/
│   ├── badge.test.tsx         # Component tests
│   └── badge-theme.test.tsx   # Theme tests
├── docs/
│   └── api/                   # Generated API documentation
├── README.md
├── package.json
└── tsconfig.json

Related Packages

• tinky - React for CLIs
• tinky-theme - Theme system for tinky
• tinky-test - Testing utilities for tinky
• tinky-ordered-list - Ordered list components

Acknowledgments

• ink-ui - Inspiration for Badge component by Vadim Demedes

License

MIT © ByteLand Technology Limited