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.

Demo: https://ui.todovue.blog/button/

Table of Contents

• Features
• Installation
• Quick Start (SPA)
• Style usage
• Nuxt 4 / SSR Usage
• Component Registration Options
• Props
• Events
• Icons
• Customization (Styles / Theming)
• Icon-only & Variant Notes
• Accessibility
• SSR Notes
• Development
• Contributing
• 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:

npm install @todovue/tv-button

Using yarn:

yarn add @todovue/tv-button

Using pnpm:

pnpm add @todovue/tv-button

Quick Start (SPA)

Global registration (main.js / main.ts):

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 <TvButton /> globally
  .mount('#app')

Local import inside a component:

<script setup>
import '@todovue/tv-button/style.css'
import { TvButton } from '@todovue/tv-button'

function onSubmit() {
  console.log('Clicked')
}
</script>

<template>
  <TvButton variant="success" icon="check" @click-button="onSubmit">Submit</TvButton>
</template>

Style usage

Vue 3 SPA with Vite

// 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

// 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):

import { defineNuxtPlugin } from '#app'
import TvButton from '@todovue/tv-button'

export default defineNuxtPlugin(nuxtApp => {
  nuxtApp.vueApp.use(TvButton)
})

Use anywhere:

<TvButton outlined icon="info">Details</TvButton>

Optional direct import (no plugin):

<script setup>
import { TvButton } from '@todovue/tv-button'
</script>

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 <button type="...">, 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:

<TvButton @click-button="onAction" />
<TvButton @click="onNative" />

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:

<TvButton icon="check" variant="success">Saved</TvButton>
<TvButton icon="info" iconPosition="left" outlined>Info</TvButton>

Customization (Styles / Theming)

Inline overrides via customStyle:

<TvButton :customStyle="{ backgroundColor: '#0f2e5b', color: '#fff' }">Branded</TvButton>

Outlined variant adapts automatically:

<TvButton outlined :customStyle="{ backgroundColor: '#ff4081', color: '#fff' }">Pink Outline</TvButton>

A subtle hover darkening is auto-generated when customStyle.backgroundColor exists.

Icon-only & Variant Notes

Pure icon button:

<TvButton type="icon" icon="edit" />

Inline icon-only action (no background / padding):

<TvButton type="icon" icon="edit" :iconOnly="true" aria-label="Edit item" />

Loading state:

<TvButton loading icon="download">Processing...</TvButton>

Link usage:

<!-- Native anchor -->
<TvButton href="https://todovvue.blog" target="_blank">External Link</TvButton>

<!-- Router link -->
<TvButton to="/dashboard">Go to Dashboard</TvButton>

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

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 and CODE_OF_CONDUCT.md.

License

MIT © TODOvue

Attributions

Crafted for the TODOvue component ecosystem