serejaris/telegram-skills / skills/tg-miniapp-ui
tg-miniapp-ui
VerifiedUse when building or debugging the interface of a Telegram Mini App: theme colors and dark mode, safe areas and notches, fullscreen, keyboard and viewport height, MainButton and SecondaryButton, BackButton, haptic feedback, performance on weak Android, or a layout bug that shows up only on a real iPhone, Android or Desktop client.
tg-miniapp-ui
Checked against the official docs on 2026-10-30: Bot API 10.3 (latest, August 24, 2026), Mini Apps page, telegram-web-app.js?64.
Not verified live
No client or device was used to write this skill. API facts come from the docs; bug reports come from public trackers. Acceptance on a real iPhone and Android device is still ahead: run the check below. A browser emulator doesn't catch these bugs.
Client bugs with platform, client, issue number and date: client-pitfalls.md. Read it before you blame your own CSS.
Startup
Put telegram-web-app.js in <head> before other scripts. Call Telegram.WebApp.ready() as soon as the essential interface is loaded: it hides the loading placeholder. expand() asks for the maximum height; isExpanded reports it.
Theme
Color everything from the theme and repaint on change. There is no separate dark mode API: colorScheme is light or dark, and the palette follows it.
body {
background: var(--tg-theme-bg-color);
color: var(--tg-theme-text-color);
}
.hint { color: var(--tg-theme-hint-color); }
.card { background: var(--tg-theme-section-bg-color, var(--tg-theme-secondary-bg-color)); }
themeParamsfields map to--tg-theme-*variables, and every field is optional. Give each a fallback. Fields by version:secondary_bg_color6.1; header, accent, section, subtitle and destructive colors 7.0;section_separator_color7.6;bottom_bar_bg_color7.10.- Listen to
themeChangedfor logic that reads colors in JS; the CSS variables update on their own. setHeaderColor,setBackgroundColorandsetBottomBarColortake#RRGGBBor keywords. PrefersetHeaderColor('bg_color'): a hex header produces light glass buttons on iOS, see pitfalls.
Viewport and keyboard
viewportHeight/--tg-viewport-heightchanges during gestures and animations, and its refresh rate is too low to follow the bottom edge.viewportStableHeight/--tg-viewport-stable-heightupdates after the app settles. Pin bottom elements to this one.viewportChangedpassesisStateStable; run layout work when it istrue.hideKeyboard()(9.1) closes the on-screen keyboard.
Safe areas
Two sets of insets, and fullscreen needs both:
| Set | Covers | CSS variables |
|---|---|---|
safeAreaInset | Notches and system navigation | --tg-safe-area-inset-{top,bottom,left,right} |
contentSafeAreaInset | Telegram's own controls | --tg-content-safe-area-inset-{top,bottom,left,right} |
.screen {
padding-top: calc(var(--tg-safe-area-inset-top, 0px) + var(--tg-content-safe-area-inset-top, 0px));
padding-bottom: var(--tg-safe-area-inset-bottom, 0px);
}
Read JS values in safeAreaChanged and contentSafeAreaChanged handlers. These events and fullscreenChanged arrive separately, so inset values read inside fullscreenChanged can be stale (tma.js #704, maintainer reply, 2025-04-03).
Fullscreen
requestFullscreen() (8.0) reports through fullscreenChanged, and failure through fullscreenFailed with UNSUPPORTED or ALREADY_FULLSCREEN. No list of supporting clients is published, and a practitioner report describes iOS 12.9 sending neither event. So handle the events and also check isFullscreen on a timer. The timeout below is a choice, not a documented value.
function enterFullscreen(onResult) {
const app = Telegram.WebApp;
if (!app.isVersionAtLeast('8.0')) return onResult(false, 'OLD_CLIENT');
let timer;
const finish = (ok, reason) => {
clearTimeout(timer);
app.offEvent('fullscreenChanged', changed);
app.offEvent('fullscreenFailed', failed);
onResult(ok, reason);
};
const changed = () => finish(app.isFullscreen, 'CHANGED');
const failed = ({ error }) => finish(error === 'ALREADY_FULLSCREEN', error);
app.onEvent('fullscreenChanged', changed);
app.onEvent('fullscreenFailed', failed);
timer = setTimeout(() => finish(app.isFullscreen, 'NO_EVENT'), 1500);
app.requestFullscreen();
}
Design the layout to work without fullscreen. Set setHeaderColor even in fullscreen, where the header is transparent: the color picks a contrasting status bar and controls. lockOrientation() keeps the current orientation (8.0).
Bottom buttons
Use MainButton and SecondaryButton instead of drawing your own bottom bar.
const { MainButton, SecondaryButton } = Telegram.WebApp;
MainButton.setParams({ text: 'Pay', is_visible: true, has_shine_effect: true });
SecondaryButton.setParams({ text: 'Cancel', is_visible: true, position: 'left' });
MainButton.onClick(async () => {
MainButton.showProgress(); // disabled while running; showProgress(true) leaves it active
try { await submit(); } finally { MainButton.hideProgress(); }
});
SecondaryButtonexists since 7.10.positionisleft(default),right,toporbottom, and applies only when both buttons are visible.setParamsalso takescolor,text_color,is_active, andicon_custom_emoji_id(9.5).onClickadds a handler, so a re-render adds another. Remove the old one withoffClick.- From the attachment menu the main button stays hidden until the user interacts with the app.
BackButton lives in the header: show(), hide(), onClick(). Wire it to your router, and hide it on the root screen.
Gestures and closing
disableVerticalSwipes()(7.7) only when swipes conflict with your own gestures; the docs recommend keeping them on. Users can still close by swiping the header.enableClosingConfirmation()(6.2) when closing would lose user input.
Haptics
HapticFeedback (6.1):
| Moment | Call |
|---|---|
| Tap or collision | impactOccurred('light' | 'medium' | 'heavy' | 'rigid' | 'soft') |
| Action result | notificationOccurred('success' | 'error' | 'warning') |
| Selection moved to another item | selectionChanged(); skip it when the user makes or confirms a choice |
Performance
The docs ask for smooth animation, ideally 60 fps. On Android the User-Agent ends with a performance class; cut animations and effects on LOW. iOS has no equivalent.
const match = navigator.userAgent.match(/Telegram-Android\/.*;\s*(LOW|AVERAGE|HIGH)\)/);
const isLowEnd = match?.[1] === 'LOW';
Official design rules
Responsive and mobile-first; interactive elements that mimic native ones; labels on all inputs and images; theme colors tracked live; safe area and content safe area respected. The page gives no spacing numbers or components.
Device check
Run on a real iPhone and a real Android phone, light and dark theme. The check is done when every line has passed on both.
- Open from each launch path you ship; the first screen has no blank area and no overlap with Telegram controls.
- Switch the system theme while the app is open; all colors follow.
- Enter fullscreen, go to another screen and back, check the top of the page.
- Focus every text field; the field stays visible and taps still work after the keyboard closes.
- Press every bottom button; progress shows, and the button recovers after a failure.
- Android low-end device: animations are cut.
Sources
- Mini Apps: https://core.telegram.org/bots/webapps · design guidelines https://core.telegram.org/bots/webapps#design-guidelines · events https://core.telegram.org/bots/webapps#events-available-for-mini-apps
telegram-web-app.js: https://telegram.org/js/telegram-web-app.js?64
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |