TODOvue Settings (TvSettings)

A flexible Vue 3 component with no framework dependencies for creating sliding settings panels from any direction. Perfect for settings, side menus, or any content that needs to slide out from screen edges. Compatible with SPA applications and server-side rendering (SSR) environments like Nuxt 3.

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

Table of Contents

• Features
• Installation
• Quick Start (SPA)
• Usage in Nuxt 4 / SSR
• Component Registration Options
• Props
• Events
• Slots
• Directions
• State Control
• Customization (Styles / Themes)
• Accessibility
• SSR Notes
• Development
• Contributing
• License

Features

• Sliding panels from 4 directions: top, right, bottom, left
• Bidirectional v-model control (controlled mode) or internal state
• Automatic close on outside click (configurable)
• Close with Escape key
• Customizable slots (header and main content)
• Built-in gear SVG icon
• Disabled state
• Smooth transitions
• Compatible with SPA and SSR (Nuxt 3)
• Tree-shake friendly (Vue marked as external in build)
• TypeScript declarations included

Installation

Using npm:

npm install @todovue/tv-settings

Using yarn:

yarn add @todovue/tv-settings

Using pnpm:

pnpm add @todovue/tv-settings

Quick Start (SPA)

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

import { createApp } from 'vue'
import App from './App.vue'
import TvSettings from '@todovue/tv-settings'

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

Local import inside a component:

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

<template>
  <TvSettings direction="right">
    <template #header>
      <h2>Settings</h2>
    </template>
    <template #default="{ close }">
      <p>Custom content</p>
      <button @click="close">Close</button>
    </template>
  </TvSettings>
</template>

Usage in Nuxt 4 / SSR

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

Use anywhere:

<TvSettings direction="left">
  <template #default="{ direction }">
    <p>Panel from {{ direction }}</p>
  </template>
</TvSettings>

Optional direct import (without plugin):

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

Component Registration Options

Approach	When to use
Global via app.use(TvSettings)	Multiple uses across the app / design system
Named local import { TvSettings }	Isolated contexts / code-split
Default direct import import TvSettings from '@todovue/tv-settings'	Single use or manual registration

Props

Prop	Type	Default	Description
modelValue	Boolean	undefined	Bidirectional v-model control. If undefined, uses internal state.
direction	String	'right'	Direction from which the panel slides: 'top', 'right', 'bottom', 'left'
disabled	Boolean	false	Disables the open button.
closeOnOutside	Boolean	true	If true, the panel closes when clicking outside.
label	String	'Open settings'	ARIA label for the gear button (accessibility).
title	String	null	Optional title to display in the header.

Events

Event (kebab)	Emit (camel)	Description
update:modelValue	update:modelValue	Emitted when open/closed state changes.
open	open	Emitted when the panel opens.
close	close	Emitted when the panel closes.

Usage:

<TvSettings 
  v-model="isOpen"
  @open="handleOpen" 
  @close="handleClose" 
/>

Slots

Slot	Bindings	Description
trigger	{ isOpen, toggle, open, close }	Replace the default gear button.
header	—	Panel header content (optional).
default	{ direction, close, open }	Main panel content with access to methods.

Slot Examples

Header slot:

<TvSettings>
  <template #header>
    <h2>My Settings</h2>
  </template>
</TvSettings>

Default slot with methods:

<TvSettings>
  <template #default="{ direction, close }">
    <p>Panel from: {{ direction }}</p>
    <button @click="close">Close</button>
  </template>
</TvSettings>

Trigger slot:

<TvSettings>
  <template #trigger="{ toggle }">
    <button @click="toggle">My Custom Button</button>
  </template>
  <template #default>
    <p>Content</p>
  </template>
</TvSettings>

Directions

The component supports 4 directions:

• top - Panel slides from top
• right - Panel slides from right (default)
• bottom - Panel slides from bottom
• left - Panel slides from left

Examples:

<TvSettings direction="top" />
<TvSettings direction="right" />
<TvSettings direction="bottom" />
<TvSettings direction="left" />

If an invalid direction is provided, the component will show a console warning and use 'right' as default.

State Control

Uncontrolled Mode (Internal State)

By default, the component manages its own state:

<TvSettings direction="left">
  <p>Panel content</p>
</TvSettings>

Controlled Mode (v-model)

Control state externally:

<script setup>
import { ref } from 'vue'
const isOpen = ref(false)
</script>

<template>
  <button @click="isOpen = !isOpen">Toggle Settings</button>
  <TvSettings v-model="isOpen" direction="right">
    <p>Controlled panel</p>
  </TvSettings>
</template>

Disable Close on Outside Click

<TvSettings :close-on-outside="false" direction="left">
  <template #default="{ close }">
    <p>Only closes with button or ESC</p>
    <button @click="close">Close</button>
  </template>
</TvSettings>

Customization (Styles / Themes)

The component uses CSS with BEM classes. You can override styles:

/* Customize gear button */
.tv-setting__gear {
  background-color: #your-color;
  color: #your-icon-color;
}

/* Customize panel */
.tv-setting__panel {
  background-color: #your-panel-bg;
  box-shadow: 0 4px 20px rgba(0,0,0,0.3);
}

/* Customize by direction */
.tv-setting--top .tv-setting__panel {
  /* specific styles for top panel */
}

Inline styles:

<TvSettings 
  direction="right"
  style="--panel-bg: #f0f0f0; --panel-width: 350px;"
>
  <p>Custom panel</p>
</TvSettings>

Accessibility

• The gear button includes aria-label, aria-pressed and aria-expanded.
• You can customize the aria-label text with the label prop.
• The panel has role="dialog".
• Supports close with Escape key.
• Proper focus management for screen readers.

Example:

<TvSettings label="Open settings panel" direction="right">
  <p>Accessible content</p>
</TvSettings>

SSR Notes

• No direct DOM access (window / document) in source code → SSR-safe.
• Styles are automatically applied when importing the library.
• Make sure to import @todovue/tv-settings/style.css in an SSR-compatible entry point (plugin or layout).
• Event listeners (outside click, keydown) are registered in onMounted to avoid SSR errors.

Development

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

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

Contributing

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

License

MIT © TODOvue

Attributions

Developed for the TODOvue component ecosystem