TODOvue logo

# TODOvue Label (TvLabel) A lightweight and customizable label (chip) component for Vue 3 designed to highlight statuses, categories, or tags within your UI. Perfect for Single Page Apps or Server-Side Rendered (SSR) environments (e.g. Nuxt 3). [![npm](https://img.shields.io/npm/v/@todovue/tv-label.svg)](https://www.npmjs.com/package/@todovue/tv-label) [![npm downloads](https://img.shields.io/npm/dm/@todovue/tv-label.svg)](https://www.npmjs.com/package/@todovue/tv-label) [![npm total downloads](https://img.shields.io/npm/dt/@todovue/tv-label.svg)](https://www.npmjs.com/package/@todovue/tv-label) ![License](https://img.shields.io/github/license/TODOvue/tv-label) ![Release Date](https://img.shields.io/github/release-date/TODOvue/tv-label) ![Bundle Size](https://img.shields.io/bundlephobia/minzip/@todovue/tv-label) ![Node Version](https://img.shields.io/node/v/@todovue/tv-label) ![Last Commit](https://img.shields.io/github/last-commit/TODOvue/tv-label) ![Stars](https://img.shields.io/github/stars/TODOvue/tv-label?style=social) > Demo: https://ui.todovue.blog/label ## Table of Contents - [Features](#features) - [Installation](#installation) - [Quick Start (SPA)](#quick-start-spa) - [Styles usage](#styles-usage) - [Nuxt 4 / SSR Usage](#nuxt-4--ssr-usage) - [Component Registration Options](#component-registration-options) - [Props](#props) - [Events](#events) - [Slots](#slots) - [Customization (Styles / Theming)](#customization-styles--theming) - [Icon Usage](#icon-usage) - [Accessibility](#accessibility) - [SSR Notes](#ssr-notes) - [Development](#development) - [Changelog](#changelog) - [Contributing](#contributing) - [License](#license) ## Features - Customizable color schemes with automatic opacity handling - Optional edit and remove icons - Flexible icon positioning (left or right) - Custom text color support - Slot-based or prop-based content - Click event handling - SSR compatible (works in Nuxt 3) - Lightweight and performant - Tree-shake friendly (Vue marked external in library build) ## Installation Using npm: ```bash npm install @todovue/tv-label ``` Using yarn: ```bash yarn add @todovue/tv-label ``` Using pnpm: ```bash pnpm add @todovue/tv-label ``` ## Quick Start (SPA) Global registration (main.js / main.ts): ```js import { createApp } from 'vue' import App from './App.vue' import '@todovue/tv-label/style.css' import { TvLabel } from '@todovue/tv-label' createApp(App) .component('TvLabel', TvLabel) .mount('#app') ``` Local import inside a component: ```vue ``` ## Styles usage ### Vue 4 / Vite (SPA) ```ts // main.ts import { createApp } from 'vue' import App from './App.vue' import '@todovue/tv-label/style.css' import { TvLabel } from '@todovue/tv-label' const app = createApp(App) app.component('TvLabel', TvLabel) app.mount('#app') ``` ### Nuxt 3 / 4 ```ts // nuxt.config.ts export default defineNuxtConfig({ modules: [ '@todovue/tv-label/nuxt' ] }) ``` ## Nuxt 4 / SSR Usage Create a plugin file: `plugins/tv-label.client.ts` (client-only is fine, or without suffix for SSR as it is safe): ```ts import { defineNuxtPlugin } from '#app' import TvLabel from '@todovue/tv-label' export default defineNuxtPlugin(nuxtApp => { nuxtApp.vueApp.use(TvLabel) }) ``` Use anywhere in your Nuxt app: ```vue ``` Optional direct import (no plugin): ```vue ``` ## Component Registration Options | Approach | When to use | |-----------------------------------------------------------------|------------------------------------------------| | Global via `app.use(TvLabel)` | Many usages across app / design system install | | Global via `app.use(TvLabelPlugin)` | Alternative plugin syntax | | Local named import `{ TvLabel }` | Isolated / code-split contexts | | Direct default import `import TvLabel from '@todovue/tv-label'` | Single usage or manual registration | ## Props | Prop | Type | Default | Description | |--------------|---------|-------------|-----------------------------------------------------------------------------------------| | color | String | `''` | Label background color in hexadecimal (e.g., `#4FC08D`). Automatically applies opacity. | | textLabel | String | `''` | Text content for the label (alternative to using the default slot). | | textColor | String | `'inherit'` | Text color for the label content. | | isEdit | Boolean | `false` | Show edit icon inside the label. | | isRemove | Boolean | `false` | Show remove icon inside the label. | | isOutline | Boolean | `false` | Applies a rounded pill shape and a solid border matching the label color. | | iconPosition | String | `'right'` | Position of icons relative to text: `'left'` or `'right'`. | | size | String | `'md'` | Size of the label: `'sm'` (small), `'md'` (medium), or `'lg'` (large). | ## Events | Event name (kebab) | Emits (camel) | Description | |--------------------|---------------|------------------------------------------------------------| | `click-label` | `clickLabel` | Custom semantic click event emitted when label is clicked. | | `click` | `click` | Native click event (also emitted). | Usage examples: ```vue ``` ## Slots | Slot name | Description | |-----------|------------------------------------------------------------------------------| | default | Main content slot for label text. If not provided, `textLabel` prop is used. | Example: ```vue ``` ## Customization (Styles / Theming) The component automatically handles color opacity and border styling based on the `color` prop: ```vue ``` The component applies: - Background color with automatic opacity (lighter shade) - 2px solid border using the full color - Customizable text color via `textColor` prop ## Icon Usage Display edit or remove icons within your labels: ```vue ``` ## Accessibility - **Semantic HTML**: The component uses a `
` with click handlers. For better accessibility, consider wrapping in a `