Vue 3 Virtual Keyboard Plugin

A professional, touch-screen optimized virtual keyboard for Vue 3 applications.

Live demo with examples: vue3.laryon.hu/vue3-virtual-keyboard

Előfeltételek

• Vue 3
• Material Design Icons (az ikonok megjelenítéséhez — opcionális, de ajánlott)

Telepítés

npm install @koleszar.norbert/vue3-virtual-keyboard

Beállítás

1. Statikus fájlok másolása (KÖTELEZŐ)

A plugin rugalmassága miatt a kiosztást és a hangokat külső fájlokból olvassa be. Másold át a következő fájlokat a csomag node_modules/@koleszar.norbert/vue3-virtual-keyboard/dist/ mappájából a saját projekted public/ mappájába:

1. keyboard-config.json → Ide kerülnek a billentyűzet kiosztások és színek.
2. click.mp3 → A gombnyomás hangja.

# Linux / macOS
cp node_modules/@koleszar.norbert/vue3-virtual-keyboard/dist/keyboard-config.json public/
cp node_modules/@koleszar.norbert/vue3-virtual-keyboard/dist/click.mp3 public/

# Windows
copy node_modules\@koleszar.norbert\vue3-virtual-keyboard\dist\keyboard-config.json public\
copy node_modules\@koleszar.norbert\vue3-virtual-keyboard\dist\click.mp3 public\

2. Plugin regisztrálása (main.js)

import { createApp } from 'vue'
import App from './App.vue'
import VirtualKeyboard from '@koleszar.norbert/vue3-virtual-keyboard'
import '@koleszar.norbert/vue3-virtual-keyboard/dist/style.css'

const app = createApp(App)

app.use(VirtualKeyboard, {
  // Opcionális: megadhatod a konfigurációs fájl egyedi útvonalát
  configUrl: '/keyboard-config.json',
})

app.mount('#app')

3. Használat a komponensekben

Helyezd el a VirtualKeyboard komponenst (lehetőleg az App.vue-ban, hogy globálisan elérhető legyen), majd használd a v-virtual-keyboard direktívát az input mezőkön.

<template>
  <div>
    <input type="text" v-virtual-keyboard v-model="textValue" placeholder="Szöveges mező" />
    <input type="number" v-virtual-keyboard v-model="numericValue" placeholder="Numerikus mező" />

    <!-- A billentyűzet komponens -->
    <VirtualKeyboard />
  </div>
</template>

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

const textValue = ref('')
const numericValue = ref(null)
</script>

A plugin Vuetify v-text-field komponensekkel is működik, de Vuetify nem kötelező előfeltétel.

Direktívák

A v-virtual-keyboard direktíva aktiválja a billentyűzetet, amikor az inputra kattintanak vagy rákoppintanak.

<!-- Automatikus felismerés az input típusából -->
<input type="text" v-virtual-keyboard />
<input type="number" v-virtual-keyboard />

<!-- Explicit kiosztás -->
<input v-virtual-keyboard="'text'" />
<input v-virtual-keyboard="'number'" />

<!-- Input-szintű konfiguráció felülírás (deep-merge a globális konfiggal) -->
<input v-virtual-keyboard="{ options: { clickSound: false } }" />
<input v-virtual-keyboard="{ type: 'number', options: { clickSound: false } }" />

A direktíva értéke lehet:

• elhagyható — a kiosztást az input type határozza meg (number → numerikus, minden más → szöveges)
• kiosztásnév string: 'text' vagy 'number'
• konfig objektum opcionális type és options mezőkkel (deep-merge a globális konfiggal, csak erre az inputra érvényes)

Témák (theme)

A plugin két beépített témával rendelkezik: "dark" (alapértelmezett) és "light". A téma a keyboard-config.json options részében állítható be:

{
  "options": {
    "theme": "light"
  }
}

Egyedi téma definiálása

A themes objektumban saját nevű témákat is létrehozhatsz, amelyek felülírják az alapértelmezett színeket:

{
  "options": {
    "theme": "custom",
    "themes": {
      "custom": {
        "keyboardBackgroundColor": "#1a1a2e",
        "buttonBackgroundColor": "#16213e",
        "functionButtonBackgroundColor": "#0f3460",
        "buttonTextColor": "#e0e0e0"
      }
    }
  }
}

A themes alatt definiált szín-tulajdonságok:

| Tulajdonság | Leírás | |---|---| | keyboardBackgroundColor | A billentyűzet háttérszíne | | buttonBackgroundColor | Az általános gombok háttérszíne | | functionButtonBackgroundColor | A funkciógombok háttérszíne (shift, backspace, spec, submit, stb.) | | buttonTextColor | A gombok szövegszíne | | accentColor | Az aktív állapot színe (shift/spec lenyomva) és a hosszú gombnyomás kijelölési kiemelése |

Téma szerinti gombszín-felülírás

Minden gombhoz megadható egy themes objektum, amelyben témánként külön állítható be a háttérszín (backgroundColor) és a szövegszín (color). Ez felülírja a globális téma szerinti értékeket az adott gombra:

{
  "keyType": "submit",
  "label": "enter",
  "icon": "mdi-arrow-left-bottom-bold",
  "flex": 2,
  "themes": {
    "dark": { "backgroundColor": "#4CAF50" },
    "light": { "backgroundColor": "#2E7D32", "color": "#ffffff" }
  }
}

Ha témafüggetlen felülírást szeretnél, használd közvetlenül a backgroundColor és color tulajdonságokat a gomb definícióján.

Konfiguráció (keyboard-config.json)

A fájl két fő részből áll:

• options: Téma, egyedi témadefiníciók, hangfájl útvonala és kiosztások.
• options.layouts: A billentyűzet kiosztásai (sorok és gombok listája).

Az options szintű tulajdonságok:

| Tulajdonság | Alapértelmezett | Leírás | |---|---|---| | theme | "dark" | Az aktív téma neve ("dark", "light", vagy egyedi) | | themes | lásd fentebb | Témánkénti szín-definíciók | | layouts | beépített | Billentyűzet kiosztás-definíciók (text, number, vagy egyedi) | | clickSound | true | Gombnyomás hangjának engedélyezése / tiltása (true / false) | | clickSoundUrl | "/click.mp3" | A gombnyomás hangfájljának útvonala |

Gomb tulajdonságok:

• label: A beírt és megjelenített karakter.
• longPress: Tömb a hosszú gombnyomásra megjelenő karakterekkel.
• spec: Karakterek a speciális (?123) módhoz.
• keyType: Funkciógombok (shift, backspace, spec, left, right, submit).
• flex: A gomb relatív szélessége (alapértelmezett: 1).
• icon: Ikonnév (pl. mdi-arrow-up-bold). Ha az ikon nem található, a label érték jelenik meg helyette.
• color: A gomb szövegszíne (téma-független fallback, felülírja a téma buttonTextColor értékét).
• backgroundColor: A gomb háttérszíne (téma-független fallback, felülírja a téma szerinti gombszínt).
• themes: Téma szerinti egyedi szín-felülírás a gombra (lásd fentebb).

Ikonok

Az alapértelmezett konfiguráció Material Design Icons ikonokat használ (mdi-* előtaggal).

MDI telepítése

npm install @mdi/font

// main.js
import '@mdi/font/css/materialdesignicons.css'

Más ikoncsomag használata

Bármilyen CSS-alapú ikoncsomag használható — a keyboard-config.json-ban csak az adott csomag osztályneveit kell megadni az icon mezőkben. Például Font Awesome esetén:

{ "keyType": "backspace", "icon": "fa-solid fa-delete-left", "flex": 1.5 }

Megjegyzés: Ha egy icon értékhez nem tartozik érvényes CSS osztály, a plugin automatikusan a label értéket jeleníti meg helyette.

Licenc

MIT

Prerequisites

• Vue 3
• Material Design Icons (for icons — optional but recommended)

Installation

npm install @koleszar.norbert/vue3-virtual-keyboard

Setup

1. Copy static files (REQUIRED)

The plugin loads its layout and sounds from external files. Copy the following files from the package's node_modules/@koleszar.norbert/vue3-virtual-keyboard/dist/ folder into your project's public/ folder:

1. keyboard-config.json → Keyboard layouts and color settings.
2. click.mp3 → Key press sound.

# Linux / macOS
cp node_modules/@koleszar.norbert/vue3-virtual-keyboard/dist/keyboard-config.json public/
cp node_modules/@koleszar.norbert/vue3-virtual-keyboard/dist/click.mp3 public/

# Windows
copy node_modules\@koleszar.norbert\vue3-virtual-keyboard\dist\keyboard-config.json public\
copy node_modules\@koleszar.norbert\vue3-virtual-keyboard\dist\click.mp3 public\

2. Register the plugin (main.js)

import { createApp } from 'vue'
import App from './App.vue'
import VirtualKeyboard from '@koleszar.norbert/vue3-virtual-keyboard'
import '@koleszar.norbert/vue3-virtual-keyboard/dist/style.css'

const app = createApp(App)

app.use(VirtualKeyboard, {
  // Optional: provide a custom path to the config file
  configUrl: '/keyboard-config.json',
})

app.mount('#app')

3. Usage in components

Place the VirtualKeyboard component (preferably in App.vue so it is globally available), then use the v-virtual-keyboard directive on input fields.

<template>
  <div>
    <input type="text" v-virtual-keyboard v-model="textValue" placeholder="Text field" />
    <input type="number" v-virtual-keyboard v-model="numericValue" placeholder="Numeric field" />

    <!-- The keyboard component -->
    <VirtualKeyboard />
  </div>
</template>

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

const textValue = ref('')
const numericValue = ref(null)
</script>

The plugin also works with Vuetify v-text-field components, but Vuetify is not a required dependency.

Directives

v-virtual-keyboard activates the keyboard when the input is tapped or clicked.

<!-- Auto-detect from input type -->
<input type="text" v-virtual-keyboard />
<input type="number" v-virtual-keyboard />

<!-- Explicit layout -->
<input v-virtual-keyboard="'text'" />
<input v-virtual-keyboard="'number'" />

<!-- Per-input config override (merged with global config) -->
<input v-virtual-keyboard="{ options: { clickSound: false } }" />
<input v-virtual-keyboard="{ type: 'number', options: { clickSound: false } }" />

The directive value can be:

• omitted — layout is inferred from input type (number → number layout, everything else → text)
• a string layout name: 'text' or 'number'
• a config object with optional type and options fields (deep-merged with global config for this input only)

Themes

The plugin has two built-in themes: "dark" (default) and "light". The theme is set in the options section of keyboard-config.json:

{
  "options": {
    "theme": "light"
  }
}

Defining a custom theme

You can define custom named themes in the themes object, overriding the default colors:

{
  "options": {
    "theme": "custom",
    "themes": {
      "custom": {
        "keyboardBackgroundColor": "#1a1a2e",
        "buttonBackgroundColor": "#16213e",
        "functionButtonBackgroundColor": "#0f3460",
        "buttonTextColor": "#e0e0e0"
      }
    }
  }
}

Color properties available under themes:

| Property | Description | |---|---| | keyboardBackgroundColor | Background color of the keyboard | | buttonBackgroundColor | Background color of regular keys | | functionButtonBackgroundColor | Background color of function keys (shift, backspace, spec, submit, etc.) | | buttonTextColor | Text color of all keys | | accentColor | Color used for active states (shift/spec pressed) and long-press selection highlight |

Per-button theme overrides

Each button can have a themes object to override colors per theme. This takes priority over the global theme colors for that specific button:

{
  "keyType": "submit",
  "label": "enter",
  "icon": "mdi-arrow-left-bottom-bold",
  "flex": 2,
  "themes": {
    "dark": { "backgroundColor": "#4CAF50" },
    "light": { "backgroundColor": "#2E7D32", "color": "#ffffff" }
  }
}

For theme-independent overrides, use backgroundColor and color directly on the button definition.

Configuration (keyboard-config.json)

The file has two main sections:

• options: Theme, custom theme definitions, sound file path, and layouts.
• options.layouts: Keyboard layouts (rows and button definitions).

Top-level options properties:

| Property | Default | Description | |---|---|---| | theme | "dark" | Active theme name ("dark", "light", or a custom name) | | themes | see above | Theme color definitions | | layouts | built-in | Keyboard layout definitions (text, number, or custom) | | clickSound | true | Enable or disable key press sound (true / false) | | clickSoundUrl | "/click.mp3" | Path to the key press sound file |

Button properties:

• label: The character typed and displayed on the key.
• longPress: Array of characters shown on long press.
• spec: Characters for the special (?123) mode.
• keyType: Function key type (shift, backspace, spec, left, right, submit).
• flex: Relative width of the key (default: 1).
• icon: Icon class name (e.g. mdi-arrow-up-bold). If the icon cannot be loaded, label is shown instead.
• color: Key text color (theme-independent fallback, overrides the theme's buttonTextColor).
• backgroundColor: Key background color (theme-independent fallback, overrides the theme's button color).
• themes: Per-theme color overrides for this button (see above).

Icons

The default configuration uses Material Design Icons (mdi-* prefix).

Installing MDI

npm install @mdi/font

// main.js
import '@mdi/font/css/materialdesignicons.css'

Using a different icon set

Any CSS-based icon library can be used — just provide the appropriate class names in the icon fields of keyboard-config.json. For example, with Font Awesome:

{ "keyType": "backspace", "icon": "fa-solid fa-delete-left", "flex": 1.5 }

Note: If an icon value does not match a valid CSS class, the plugin automatically falls back to displaying the label value.

License

MIT