A lightweight package for seamless integration of Telegram Mini Apps and Telegram Widgets features.
<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>Install package:
npm i vue-tg@betaTo 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>In addition to static typing, the library enforces runtime feature support checks to prevent runtime 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.
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.
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.
Available components:
- Alert
- BackButton
- BiometricManager
- ClosingConfirmation
- Confirm
- ExpandedViewport
- MainButton
- Popup
- ScanQr
- SecondaryButton
- SettingsButton
| Field | Composable |
|---|---|
| initData | useMiniApp |
| initDataUnsafe | useMiniApp |
| version | useMiniApp |
| platform | useMiniApp |
| colorScheme | useTheme |
| themeParams | useTheme |
| isActive | useMiniApp |
| isExpanded | useViewport |
| viewportHeight | useViewport |
| viewportStableHeight | useViewport |
| headerColor | useTheme |
| backgroundColor | useTheme |
| isClosingConfirmationEnabled | useMiniApp |
| isVerticalSwipesEnabled | useViewport |
| isFullscreen | useViewport |
| isOrientationLocked | useViewport |
| safeAreaInset | useViewport |
| contentSafeAreaInset | useViewport |
| BackButton | useBackButton |
| MainButton | useMainButton |
| SecondaryButton | useSecondaryButton |
| SettingsButton | useSettingsButton |
| HapticFeedback | useHapticFeedback |
| CloudStorage | useCloudStorage |
| BiometricManager | useBiometricManager |
| Accelerometer | useAccelerometer |
| DeviceOrientation | useDeviceOrientation |
| Gyroscope | useGyroscope |
| LocationManager | useLocationManager |
| DeviceStorage | useDeviceStorage |
| SecureStorage | useSecureStorage |
| isVersionAtLeast | useMiniApp |
| setHeaderColor | useTheme |
| setBackgroundColor | useTheme |
| setBottomBarColor | useTheme |
| enableClosingConfirmation | useMiniApp |
| disableClosingConfirmation | useMiniApp |
| enableVerticalSwipes | useViewport |
| disableVerticalSwipes | useViewport |
| requestFullscreen | useViewport |
| exitFullscreen | useViewport |
| lockOrientation | useViewport |
| unlockOrientation | useViewport |
| addToHomeScreen | useHomeScreen |
| checkHomeScreenStatus | useHomeScreen |
| onEvent | Event Handling |
| offEvent | Managing Event Subscriptions |
| sendData | useMiniApp |
| switchInlineQuery | useMiniApp |
| openLink | useMiniApp |
| openTelegramLink | useMiniApp |
| openInvoice | useMiniApp |
| shareToStory | useMiniApp |
| shareMessage | useMiniApp |
| setEmojiStatus | useEmojiStatus |
| requestEmojiStatusAccess | useEmojiStatus |
| downloadFile | useMiniApp |
| showPopup | usePopup |
| showAlert | usePopup |
| showConfirm | usePopup |
| showScanQrPopup | useQrScanner |
| closeScanQrPopup | useQrScanner |
| readTextFromClipboard | useClipboard |
| requestWriteAccess | useMiniApp |
| requestContact | useMiniApp |
| ready | useMiniApp |
| expand | useViewport |
| close | useMiniApp |