Enables creation of Telegram mini apps, offering features like viewport management, theme adaptation, and seamless integration with Telegram WebApp API for enhanced user experience.
Surfaced from shared tags and platforms — no rankings paid for.
Kotlin Multiplatform library for building Telegram Mini Apps with Compose Multiplatform on jsMain.
It provides:
telegramWebApp { ... } entry point for Compose UIwindow.Telegram.WebApp2.3.101.10.06.9For Telegram features added in later Bot API versions, check the runtime version with webApp.isVersionAtLeast(...) before using them.
js targetjsMainAdd the Telegram runtime script to your page:
<script src="https://telegram.org/js/telegram-web-app.js"></script>
Add the library dependency:
dependencies {
implementation("io.github.kirillNay:tg-mini-app:1.2.0")
}
Use telegramWebApp as the entry point of your Telegram-hosted web app:
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.material3.Surface
import androidx.compose.material3.Text
import com.kirillNay.telegram.miniapp.compose.telegramWebApp
import com.kirillNay.telegram.miniapp.webApp.webApp
fun main() {
telegramWebApp { style ->
LaunchedEffect(Unit) {
webApp.ready()
webApp.expand()
}
Surface(
color = style.colors.backgroundColor,
) {
Text("Hello, ${webApp.initDataUnsafe.user?.firstName ?: "Telegram"}")
}
}
}
telegramWebApp gives your content a TelegramStyle instance with:
style.colors - current Telegram theme colors mapped to Compose Colorstyle.viewPort.viewPortHeight - current visible Mini App heightstyle.viewPort.viewportStableHeight - stable viewport height for bottom-pinned UIBoth viewport and theme values are refreshed when Telegram emits corresponding WebApp events.
The library adds only a thin Compose integration layer:
telegramWebApp { style ->
App(
background = style.colors.backgroundColor,
primary = style.colors.buttonColor,
viewportHeight = style.viewPort.viewportStableHeight,
)
}
This makes it easy to keep Telegram-specific code near your jsMain entry point while the rest of your UI stays platform-agnostic.
Use the global webApp instance to access Telegram Mini App features in Kotlin style.
import com.kirillNay.telegram.miniapp.webApp.webApp
webApp.ready()
webApp.expand()
webApp.enableClosingConfirmation(true)
webApp.setBackgroundColor("bg_color")
webApp.setHeaderColor("secondary_bg_color")
webApp.showConfirm("Exit checkout?") { isConfirmed ->
if (isConfirmed) {
webApp.close()
}
}
webApp.backButton.onClick { navigateBack() }
webApp.backButton.show()
webApp.mainButton
.setText("Pay")
.onClick { submitOrder() }
.show()
suspend fun saveDraft(note: String) {
webApp.cloudStorage.setItem("draft_note", note)
}
suspend fun loadDraft(): String {
return webApp.cloudStorage.getItem("draft_note").getOrDefault("")
}
webApp.hapticFeedback.impactOccurred("light")
webApp.hapticFeedback.notificationOccurred("success")
jsMain. It is not a general-purpose browser wrapper.window.Telegram.WebApp must be available before you use or .The repository includes a complete sample in samples/coffee-order-demo:
commonMainjsMainYou can also try the Telegram demo bot at @tgminiapp_demo_bot or open it directly: t.me/tgminiapp_demo_bot/demo.
Run the sample from the repository root:
./gradlew -p samples/coffee-order-demo :composeApp:jsBrowserDevelopmentRun
./gradlew -p samples/coffee-order-demo :composeApp:assembleDebug
./gradlew -p samples/coffee-order-demo :composeApp:linkDebugFrameworkIosSimulatorArm64
More details are available in samples/coffee-order-demo/README.md.
The wrapper includes typed access to commonly used Telegram WebApp features, including:
The API is designed to stay close to the official Telegram Mini Apps documentation, but exposed with Kotlin naming and suspend-friendly wrappers where it improves ergonomics.
telegramWebAppwebAppinitDataUnsafe as untrusted client data. Validate rawInitData on your server as described in the Telegram docs.