Mini App

The 💠component responsible for managing functionality within Telegram Mini Apps.

Mounting

Before using this component, it must be mounted using the mount method, which updates the isMounted signal property.

Variable

import { miniApp } from '@telegram-apps/sdk';

miniApp.mount();
miniApp.isMounted(); // true

Functions

import { mountMiniApp, isMiniAppMounted } from '@telegram-apps/sdk';

mountMiniApp();
isMiniAppMounted(); // true

INFO

The mount method also mounts the Theme Params scope to extract correctly configured values.

To unmount the component, use the unmount method:

Variable

miniApp.unmount();
miniApp.isMounted(); // false

Functions

import { unmountMiniApp, isMiniAppMounted } from '@telegram-apps/sdk';

unmountMiniApp();
isMiniAppMounted(); // false

Binding CSS Variables

To expose the miniApp properties via CSS variables, use the bindCssVars method. The isCssVarsBound signal property is updated after the method is called.

This method optionally accepts a function that transforms the values bgColor and headerColor into CSS variable names. By default, values are converted to kebab case with the prefix --tg-.

Variable

miniApp.bindCssVars();
// Creates CSS variables like:
// --tg-bg-color: #aabbcc
// --tg-header-color: #aabbcc

miniApp.bindCssVars(key => `--my-prefix-${key}`);
// Creates CSS variables like:
// --my-prefix-bgColor: #aabbcc
// --my-prefix-headerColor: #aabbcc

miniApp.isCssVarsBound(); // true

Functions

import { bindMiniAppCssVars, isMiniAppCssVarsBound } from '@telegram-apps/sdk';

bindMiniAppCssVars();
// Creates CSS variables like:
// --tg-bg-color: #aabbcc
// --tg-header-color: #aabbcc

bindMiniAppCssVars(key => `--my-prefix-${key}`);
// Creates CSS variables like:
// --my-prefix-bgColor: #aabbcc
// --my-prefix-headerColor: #aabbcc

isMiniAppCssVarsBound(); // true

Header Color

To change the mini application header color, the method setHeaderColor is used. In turn, calling this method updates the headerColor signal property value.

The method accepts either an RGB color value or one of the following strings: bg_color, secondary_bg_color.

Variable

if (miniApp.setHeaderColor.isSupported()) {
  miniApp.setHeaderColor('bg_color');
  miniApp.headerColor(); // 'bg_color'
}

if (
  miniApp.setHeaderColor.isSupported()
  && miniApp.setHeaderColor.supports('color')
) {
  miniApp.setHeaderColor('#aabbcc');
  miniApp.headerColor(); // '#aabbcc'
}

Functions

import {
  setMiniAppHeaderColor,
  miniAppHeaderColor,
} from '@telegram-apps/sdk';

if (setMiniAppHeaderColor.isSupported()) {
  setMiniAppHeaderColor('bg_color');
  miniAppHeaderColor(); // 'bg_color'
}

if (
  setMiniAppHeaderColor.isSupported()
  && setMiniAppHeaderColor.supports('color')
) {
  setMiniAppHeaderColor('#aabbcc');
  miniAppHeaderColor(); // '#aabbcc'
}

Background Color

To update the mini application background color, use the setBackgroundColor method. Calling this method updates the headerColor signal property value.

Variable

if (miniApp.setBackgroundColor.isSupported()) {
  miniApp.setBackgroundColor('#ffffff');
  miniApp.backgroundColor(); // '#ffffff'
}

Functions

import { 
  setMiniAppBackgroundColor,
  miniAppBackgroundColor,
} from '@telegram-apps/sdk';

if (setMiniAppBackgroundColor.isSupported()) {
  setMiniAppBackgroundColor('#ffffff');
  miniAppBackgroundColor(); // '#ffffff'
}

Methods

close

To close the mini application, use the close method.

Variable

miniApp.close();

Functions

import { closeMiniApp } from '@telegram-apps/sdk';

closeMiniApp();

ready

To signal that the Mini App is ready to be displayed, use the ready method. Once called, the loading placeholder is hidden, and the Mini App is shown.

Variable

miniApp.ready();

Functions

import { miniAppReady } from '@telegram-apps/sdk';

miniAppReady();

TIP

Call this function as early as possible after loading essential interface elements to ensure a smooth user experience.