Дизайн интерфейсов под Telegram Mini Apps

Что такое Mini App

Telegram Mini App — это веб-приложение внутри Telegram. По сути обычный сайт, но с доступом к WebApp SDK и под жёсткие гайдлайны платформы.

Главные отличия от веба

• Нет браузерного хрома — приложение занимает весь viewport
• Тема меняется системно — нужно подхватывать themeParams
• Нативная клавиатура — input ведёт себя как в нативном приложении
• Жесты — свайп вниз закрывает модалку

Подхват темы

import { useEffect, useState } from "react";
 
export function useTelegramTheme() {
  const [theme, setTheme] = useState<"light" | "dark">("dark");
 
  useEffect(() => {
    const tg = window.Telegram?.WebApp;
    if (!tg) return;
    setTheme(tg.colorScheme);
    tg.onEvent("themeChanged", () => setTheme(tg.colorScheme));
  }, []);
 
  return theme;
}

MainButton vs обычная кнопка

Telegram даёт нативную кнопку внизу экрана через tg.MainButton. Используйте её для основного действия — пользователи к ней привыкли. Свои inline-кнопки — для второстепенных.

Высота viewport

window.innerHeight лжёт в Telegram. Используйте tg.viewportHeight — она обновляется при появлении клавиатуры и других UI-событиях.

Итог

Mini App — это не обычный лендинг и не нативное приложение. Это отдельный формат со своими ритуалами. Чем точнее им следовать, тем выше шансы, что пользователь не закроет окно через секунду.