TODOvue Modal (TvModal)

A flexible, customizable Vue 3 modal component with multiple variants (success, error, warning, info), animations, theme support, and accessibility features. Works seamlessly in Single Page Apps and Server-Side Rendered (SSR) environments like Nuxt 3.

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

Table of Contents

• Features
• Installation
• Quick Start (SPA)
• Nuxt 4 / SSR Usage
• Component Registration Options
• Props
• Events
• Configuration Object
• Theme Support
• Theme Support
• Slots
• Usage Examples
• Animations
• Accessibility
• SSR Notes
• Development
• Contributing
• License

Features

• Multiple visual variants: success, error, warning, info
• Configurable title, description, and action buttons
• Built-in animations (scale-up, scale-down, rotate shake on overlay click)
• Theme support: auto-detect dark/light mode or manual override
• Uses Vue Teleport for proper modal rendering
• Keyboard navigation (ESC to close)
• Focus management and restoration
• Accessible (ARIA attributes, role="dialog")
• Works in SPA and SSR (Nuxt 3) contexts
• Integrates with @todovue/tv-button for action buttons
• Tree-shake friendly (Vue marked external in library build)

Installation

Using npm:

npm install @todovue/tv-modal

Using yarn:

yarn add @todovue/tv-modal

Using pnpm:

pnpm add @todovue/tv-modal

Importing Styles

Important: Starting from version 1.0.0+, TvModal no longer injects CSS automatically. You must explicitly import the stylesheet in your application.

For Vue/Vite SPA:

// main.ts
import { createApp } from 'vue'
import App from './App.vue'

import '@todovue/tv-modal/style.css'
import '@todovue/tv-button/style.css'
import { TvModal } from '@todovue/tv-modal'

const app = createApp(App)
app.component('TvModal', TvModal)
app.mount('#app')

For Nuxt 3/4:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@todovue/tv-modal/nuxt'
  ]
})

Then register the component in a plugin as shown in the Nuxt 3 / SSR Usage section.

Quick Start (SPA)

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

import { createApp } from 'vue'
import App from './App.vue'
import '@todovue/tv-modal/style.css'
import TvModal from '@todovue/tv-modal'

createApp(App)
  .use(TvModal) // enables <TvModal /> globally
  .mount('#app')

Local import inside a component:

<script setup>
import { ref } from 'vue'
import { TvModal } from '@todovue/tv-modal'

const modal = ref()

const modalConfig = {
  title: "Confirm Action",
  description: "Are you sure you want to proceed?",
  confirmButtonText: "Yes",
  cancelButtonText: "No",
  icon: "warning"
}

const openModal = () => {
  modal.value.openModal()
}

const handleAccepted = () => {
  console.log('User confirmed')
}

const handleCanceled = () => {
  console.log('User canceled')
}
</script>

<template>
  <button @click="openModal">Open Modal</button>
  
  <TvModal
    :config-modal="modalConfig"
    @accepted="handleAccepted"
    @canceled="handleCanceled"
    ref="modal"
  />
</template>

Note: Don't forget to import the CSS in your main entry file as shown above.

Nuxt 4 / SSR Usage

First, add the CSS to your nuxt.config.ts:

// nuxt.config.ts
export default defineNuxtConfig({
  css: ['@todovue/tv-modal/style.css'],
})

Then create a plugin file: plugins/tv-modal.client.ts:

import { defineNuxtPlugin } from '#app'
import TvModal from '@todovue/tv-modal'

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

Use anywhere in your Nuxt app:

<template>
  <button @click="modal.openModal()">Show Modal</button>
  
  <TvModal
    :config-modal="config"
    @accepted="handleAccept"
    ref="modal"
  />
</template>

<script setup>
import { ref } from 'vue'

const modal = ref()
const config = {
  title: "Success!",
  description: "Operation completed",
  confirmButtonText: "OK",
  icon: "success"
}

const handleAccept = () => {
  // Handle acceptance
}
</script>

Optional direct import (no plugin):

<script setup>
import { TvModal } from '@todovue/tv-modal'
</script>

Component Registration Options

| Approach | When to use | |-----------------------------------------------------------------|------------------------------------------------| | Global via app.use(TvModal) | Many usages across app / design system install | | Local named import { TvModal } | Isolated / code-split contexts | | Direct default import import TvModal from '@todovue/tv-modal' | Single usage or manual registration |

Props

| Prop | Type | Default | Description | |-----------------|---------|---------|-------------------------------------------------------------------------------| | configModal | Object | — | Required. Configuration object for modal content and buttons (see below). | | theme | String | '' | Theme override: '' (auto-detect), 'dark-mode', or 'light-mode'. | | closeOnBackdrop | Boolean | false | If true, clicking the backdrop closes the modal. Default is false. |

Events

| Event name | Payload | Description | |------------|---------|--------------------------------------------------| | accepted | — | Emitted when user clicks the confirm button. | | canceled | — | Emitted when user clicks cancel or presses ESC. |

Usage:

<TvModal
  :config-modal="config"
  @accepted="onAccept"
  @canceled="onCancel"
  ref="modal"
/>

Configuration Object

The configModal prop accepts an object with the following properties:

| Property | Type | Required | Description | |----------------------|--------|----------|------------------------------------------------------------------------| | title | String | No* | Modal title text. | | description | String | No* | Modal description/body text. | | confirmButtonText | String | No | Text for the confirm button. If omitted, button won't show. | | confirmButtonVariant | String | No | Variant for confirm button (e.g. success, danger). Def: success. | | cancelButtonText | String | No | Text for the cancel button. If omitted, button won't show. | | cancelButtonVariant | String | No | Variant for cancel button. (e.g. success, danger). Def: success. | | icon | String | No | Icon variant: 'success', 'error', 'warning', or 'info'. |

* At least one of title or description is required (validated by prop validator).

Example:

const modalConfig = {
  title: "Delete Item",
  description: "This action cannot be undone. Are you sure?",
  confirmButtonText: "Delete",
  cancelButtonText: "Cancel",
  icon: "warning"
}

Theme Support

TvModal automatically detects the theme from your application:

• Checks document.body for .dark-mode or .light-mode classes
• Checks #app element for theme classes
• Falls back to searching for any .dark-mode or .light-mode element
• Observes DOM changes to update theme dynamically

Manual override:

<TvModal :config-modal="config" theme="dark-mode" ref="modal" />

Slots

TvModal provides slots for full content customization, allowing you to go beyond simple text and standard structures.

| Slot Name | Description | |-----------|------------------------------------------------------------------------------| | header | Replaces the default icon and title area. | | default | The main body of the modal. Replaces the standard description text. | | footer | Replaces the default action buttons. You must handle closing logic manually. |

Note: You can mix and match configuration props with slots. For example, use configModal.title for the title and the default slot for a custom form body.

Usage Examples

Success Modal

<script setup>
import { ref } from 'vue'
import { TvModal } from '@todovue/tv-modal'

const modal = ref()
const config = {
  title: "Success!",
  description: "Your operation was completed successfully",
  confirmButtonText: "Great!",
  icon: "success"
}
</script>

<template>
  <button @click="modal.openModal()">Show Success</button>
  <TvModal :config-modal="config" @accepted="() => {}" ref="modal" />
</template>

Error Modal

<script setup>
import { ref } from 'vue'
import { TvModal } from '@todovue/tv-modal'

const modal = ref()
const config = {
  title: "Error occurred",
  description: "Something went wrong. Please try again later.",
  confirmButtonText: "OK",
  cancelButtonText: "Cancel",
  icon: "error"
}
</script>

<template>
  <button @click="modal.openModal()">Show Error</button>
  <TvModal
    :config-modal="config"
    @accepted="handleRetry"
    @canceled="handleCancel"
    ref="modal"
  />
</template>

Warning Modal

<script setup>
import { ref } from 'vue'
import { TvModal } from '@todovue/tv-modal'

const modal = ref()
const config = {
  title: "Are you sure?",
  description: "If you delete it there is no step back",
  confirmButtonText: "Yes, delete it",
  cancelButtonText: "No, keep it",
  icon: "warning"
}
</script>

<template>
  <button @click="modal.openModal()">Delete Item</button>
  <TvModal
    :config-modal="config"
    @accepted="deleteItem"
    @canceled="() => {}"
    ref="modal"
  />
</template>

Info Modal

<script setup>
import { ref } from 'vue'
import { TvModal } from '@todovue/tv-modal'

const modal = ref()
const config = {
  title: "Information",
  description: "Here is some important information you should know about.",
  confirmButtonText: "Got it",
  icon: "info"
}
</script>

<template>
  <button @click="modal.openModal()">Show Info</button>
  <TvModal :config-modal="config" @accepted="() => {}" ref="modal" />
</template>

With Slots (Custom Content)

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

const modal = ref()
// Config is minimal if using full slots, or you can mix them
const config = { title: "Custom Form" }

const handleSave = () => {
  // Logic here
  modal.value.acceptModal() // Manually trigger close/animate
}
</script>

<template>
  <button @click="modal.openModal()">Open Custom Modal</button>
  
  <TvModal :config-modal="config" ref="modal">
    <template #header>
      <h3 class="custom-title">My Custom Header</h3>
    </template>
    
    <div class="my-form">
      <input type="text" placeholder="Enter name" />
    </div>

    <template #footer>
      <TvButton @click="handleSave">Save</TvButton>
      <TvButton variant="danger" @click="modal.cancelModal()">Close</TvButton>
    </template>
  </TvModal>
</template>

Animations

TvModal includes built-in animations:

• Scale up: When modal opens
• Scale down: When modal closes
• Rotate shake: When user clicks the overlay (attention grabber)

Animations are managed internally via the useModal composable and applied via CSS classes.

Accessibility

• Uses Vue <Teleport> to render modal at the body level
• Proper ARIA attributes: role="dialog", aria-modal="true"
• Dynamic aria-labelledby and aria-describedby based on title/description
• Keyboard support: ESC key to close/cancel
• Focus management:
  • Focuses modal on open
  • Restores focus to triggering element on close
• Action buttons use the accessible @todovue/tv-button component

SSR Notes

• Safe for SSR (no direct window/document access during module evaluation)
• Uses onMounted for theme detection and DOM observers
• Teleport target is body (ensure it exists in SSR context)
• Theme detection gracefully handles typeof document === 'undefined'
• Works seamlessly with Nuxt 3

Development

git clone https://github.com/TODOvue/tv-modal.git
cd tv-modal
npm install
npm run dev     # run demo playground
npm run build   # build library

Local demo served from Vite using index.html and demo examples in src/demo.

Contributing

PRs and issues welcome. See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

Dependencies

• Runtime: @todovue/tv-button (for action buttons)
• Peer: vue@^3.0.0

License

MIT © TODOvue

Attributions

Crafted for the TODOvue component ecosystem