README.md

March 3, 2026 · View on GitHub

vue-tg - Telegram integration for Vue

docs version downloads

A lightweight package for seamless integration of Telegram Mini Apps and Telegram Widgets features.

Usage Example

<template>
  <MainButton text="Open alert" @click="() => popup.showAlert('Hello!')" />
</template>

<script lang="ts" setup>
import { MainButton } from 'vue-tg'
import { usePopup } from 'vue-tg/latest'

const popup = usePopup()
</script>

Installation

Install package:

npm i vue-tg

To connect your Mini App to the Telegram client, place the script telegram-web-app.js in the <head> tag before any other scripts, using this code:

<script src="https://telegram.org/js/telegram-web-app.js"></script>

Features

Type Safety

In addition to static typing, the library enforces runtime feature support checks to prevent errors on clients with outdated Bot API support.

const deviceStorage = useDeviceStorage()

// ❌ Type error:
// 'getItem' may not be available — DeviceStorage was introduced in Bot API 9.0
deviceStorage.getItem('token')

if (deviceStorage.isVersionAtLeast('9.0')) {
  // ✅ Safe to use
  deviceStorage.getItem('token')
}

You can opt out of these checks or define a minimum required Bot API version, which disables warnings for features introduced up to that version. For details, see the versioning section in the documentation.

Reactivity

You can react to changes using the standard Vue reactivity pattern:

const miniApp = useMiniApp()

watch(miniApp.isActive, (isActive) => {
  if (isActive)
    startUpdating()
  else
    stopUpdating()
})

The isActive field is reactive, so it can be used in watch, computed, or any other reactive context.

In the documentation, all reactive fields are marked with reactive tag.

Async Support

You can use async/await to work with methods — no need to nest callbacks.

const miniApp = useMiniApp()
const qrScanner = useQrScanner()
const popup = usePopup()

// Old callback-style flow
qrScanner.show({ text: 'Scan URL' }, (url) => {
  popup.showConfirm(`Open ${url}?`, (ok) => {
    if (ok) {
      miniApp.openLink(url)
    }
  })
})

// The modern way — flat and readable
const url = await qrScanner.show({ text: 'Scan URL' })
const ok = await popup.showConfirm(`Open ${url}?`)
if (ok) {
  miniApp.openLink(url)
}

Methods that support async execution are marked with async tag in the documentation. Callback-style usage is still available for compatibility.

Components

Available components:

Widgets

Documentation

Instructions

Mapping

FieldComposable
initDatauseMiniApp
initDataUnsafeuseMiniApp
versionuseMiniApp
platformuseMiniApp
colorSchemeuseTheme
themeParamsuseTheme
isActiveuseMiniApp
isExpandeduseViewport
viewportHeightuseViewport
viewportStableHeightuseViewport
headerColoruseTheme
backgroundColoruseTheme
isClosingConfirmationEnableduseMiniApp
isVerticalSwipesEnableduseViewport
isFullscreenuseViewport
isOrientationLockeduseViewport
safeAreaInsetuseViewport
contentSafeAreaInsetuseViewport
BackButtonuseBackButton
MainButtonuseMainButton
SecondaryButtonuseSecondaryButton
SettingsButtonuseSettingsButton
HapticFeedbackuseHapticFeedback
CloudStorageuseCloudStorage
BiometricManageruseBiometricManager
AccelerometeruseAccelerometer
DeviceOrientationuseDeviceOrientation
GyroscopeuseGyroscope
LocationManageruseLocationManager
DeviceStorageuseDeviceStorage
SecureStorageuseSecureStorage
isVersionAtLeastuseMiniApp
setHeaderColoruseTheme
setBackgroundColoruseTheme
setBottomBarColoruseTheme
enableClosingConfirmationuseMiniApp
disableClosingConfirmationuseMiniApp
enableVerticalSwipesuseViewport
disableVerticalSwipesuseViewport
requestFullscreenuseViewport
exitFullscreenuseViewport
lockOrientationuseViewport
unlockOrientationuseViewport
addToHomeScreenuseHomeScreen
checkHomeScreenStatususeHomeScreen
onEventEvent Handling
offEventManaging Event Subscriptions
sendDatauseMiniApp
switchInlineQueryuseMiniApp
openLinkuseMiniApp
openTelegramLinkuseMiniApp
openInvoiceuseMiniApp
shareToStoryuseMiniApp
shareMessageuseMiniApp
setEmojiStatususeEmojiStatus
requestEmojiStatusAccessuseEmojiStatus
downloadFileuseMiniApp
hideKeyboarduseMiniApp
showPopupusePopup
showAlertusePopup
showConfirmusePopup
showScanQrPopupuseQrScanner
closeScanQrPopupuseQrScanner
readTextFromClipboarduseClipboard
requestWriteAccessuseMiniApp
requestContactuseMiniApp
readyuseMiniApp
expanduseViewport
closeuseMiniApp