# TODOvue Button (TvButton) A flexible, framework‑agnostic Vue 3 button component with variants, sizes, icons, loading state, and customization utilities. Ship it in Single Page Apps or Server-Side Rendered (SSR) environments (e.g. Nuxt 3) with zero DOM assumptions. [](https://www.npmjs.com/package/@todovue/tv-button) [](https://www.npmjs.com/package/@todovue/tv-button) [](https://www.npmjs.com/package/@todovue/tv-button)       > Demo: https://ui.todovue.blog/button/ ## Table of Contents - [Features](#features) - [Installation](#installation) - [Quick Start (SPA)](#quick-start-spa) - [Style usage](#style-usage) - [Nuxt 4 / SSR Usage](#nuxt-4--ssr-usage) - [Component Registration Options](#component-registration-options) - [Props](#props) - [Events](#events) - [Icons](#icons) - [Customization (Styles / Theming)](#customization-styles--theming) - [Icon-only & Variant Notes](#icon-only--variant-notes) - [Accessibility](#accessibility) - [SSR Notes](#ssr-notes) - [Development](#development) - [Contributing](#contributing) - [License](#license) ## Features - **Variants**: primary, secondary, success, info, warning, error - **Sizes**: sm, md, lg, full-width option - Icon support (pre-bundled SVG set via `import.meta.glob`) - Icon-only and pure icon modes (`type="icon"` + `iconOnly`) - Loading state with spinner - Custom inline style override via `customStyle` - Emits both a custom event and the native click - Works in SPA and SSR (Nuxt 3) contexts - Tree-shake friendly (Vue marked external in library build) ## Installation Using npm: ```bash npm install @todovue/tv-button ``` Using yarn: ```bash yarn add @todovue/tv-button ``` Using pnpm: ```bash pnpm add @todovue/tv-button ``` ## Quick Start (SPA) Global registration (main.js / main.ts): ```js import { createApp } from 'vue' import App from './App.vue' import '@todovue/tv-button/style.css' import TvButton from '@todovue/tv-button' createApp(App) .use(TvButton) // enables globally .mount('#app') ``` Local import inside a component: ```vue ``` ## Style usage ### Vue 3 SPA with Vite ```ts // main.ts import { createApp } from 'vue' import App from './App.vue' import '@todovue/tv-button/style.css' import { TvButton } from '@todovue/tv-button' const app = createApp(App) app.component('TvButton', TvButton) app.mount('#app') ``` ### Nuxt 3/4 ```ts // nuxt.config.ts export default defineNuxtConfig({ modules: [ '@todovue/tv-button/nuxt' ] }) ``` ## Nuxt 4 / SSR Usage Create a plugin file: `plugins/tv-button.client.ts` (client-only is fine, or without suffix for SSR as it is safe): ```ts import { defineNuxtPlugin } from '#app' import TvButton from '@todovue/tv-button' export default defineNuxtPlugin(nuxtApp => { nuxtApp.vueApp.use(TvButton) }) ``` Use anywhere: ```vue Details ``` Optional direct import (no plugin): ```vue ``` ## Component Registration Options | Approach | When to use | |-------------------------------------------------------------------|------------------------------------------------| | Global via `app.use(TvButton)` | Many usages across app / design system install | | Local named import `{ TvButton }` | Isolated / code-split contexts | | Direct default import `import TvButton from '@todovue/tv-button'` | Single usage or manual registration | ## Props All boolean style props have two interchangeable forms: a long form (`isSomething`) and a short alias. | Prop | Type | Default | Description | |--------------|-------------------------------------------|-----------|--------------------------------------------------------| | buttonText | string | '' | Optional text (alternative to slot). | | variant | 'primary' \| 'secondary' \| 'success' ... | 'primary' | Visual style variant. | | size | 'sm' \| 'md' \| 'lg' | 'md' | Button size. | | customStyle | object | {} | Inline style overrides (`{ backgroundColor, color }`). | | icon | string | null | Name of bundled icon. | | iconColor | string | 'white' | Icon color override. | | iconPosition | 'left' \| 'right' | 'right' | Icon position relative to text. | | type | 'button' \| 'submit' \| 'reset' \| 'icon' | 'button' | Native button type. Use 'icon' for icon-only styling. | | ariaLabel | string | '' | Accessibility label (required if no text / icon-only). | | iconOnly | boolean | false | Renders only the icon (no padding/background). | | outlined | boolean | false | Outlined style. | | rounded | boolean | false | Rounded corners. | | disabled | boolean | false | Disables interaction. | | loading | boolean | false | Shows spinner & disables. | | full | boolean | false | Full width. | | text | boolean | false | Text (minimal) style. | | href | string | null | URL for native anchor tag. | | to | string \| object | null | Route for RouterLink / NuxtLink. | | target | string | null | Anchor target (e.g. '_blank'). | | rel | string | null | Anchor rel attribute. | > Note: Because `type` is bound to the native ``, using `type="icon"` produces a non-standard button attribute. This does not break rendering but is semantically incorrect in forms. A future release will introduce `variant` and keep `htmlType` separate (see Roadmap). ## Events | Event name (kebab) | Emits (camel) | Description | |--------------------|---------------|---------------------------------------------| | `click-button` | `clickButton` | Custom semantic click event. | | `click` | `click` | Native passthrough (also emitted manually). | Usage: ```vue ``` ## Icons Set with the `icon` prop. Available names: `account`, `add-user`, `alert`, `arrow-down`, `arrow-left`, `arrow-right`, `arrow-up`, `block`, `calendar`, `cancel`, `check`, `clone`, `dark`, `download`, `edit`, `external-link`, `favorite`, `filter`, `help`, `info`, `light`, `loading`, `lock`, `login`, `logout`, `menu`, `minus`, `notification`, `plus`, `remove`, `search`, `settings`, `share`, `star`, `todovue`, `unlock`, `update`, `view` `double-arrow-left`, `double-arrow-right`, `home`, `dots-vertical`, `eye-off`, `trash`, `upload`, `dashboard`, `folder`, `link`, `mail` and `save`. Example: ```vue Saved Info ``` ## Customization (Styles / Theming) Inline overrides via `customStyle`: ```vue Branded ``` Outlined variant adapts automatically: ```vue Pink Outline ``` > A subtle hover darkening is auto-generated when `customStyle.backgroundColor` exists. ## Icon-only & Variant Notes Pure icon button: ```vue ``` Inline icon-only action (no background / padding): ```vue ``` Loading state: ```vue Processing... ``` Link usage: ```vue External Link Go to Dashboard ``` ## Accessibility - Always provide visible text OR `aria-label`. - Mandatory: add `aria-label` when using `iconOnly` or when slot content is empty. - Disabled state uses both `disabled` attribute and styling classes. ## SSR Notes - No direct DOM (`window` / `document`) access in source → safe for SSR. - Styles are now served from a separate CSS file generated by Vite (`dist/tv-button.css`). You need to import it explicitly in your app (SPA or Nuxt) using `@todovue/tv-button/style.css`. - SVG icons are bundled via Vite's `import.meta.glob` (works in Vite + Nuxt). ## Development ```bash git clone https://github.com/TODOvue/tv-button.git cd tv-button yarn install yarn dev # run demo playground yarn build # build library ``` Local demo served from Vite using `index.html` + `src/demo` examples. ## Contributing PRs and issues welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md). ## License MIT © TODOvue ### Attributions Crafted for the TODOvue component ecosystem