Viewport

The 💠component responsible for the Telegram Mini Apps viewport.

Mounting

Before using the component, it is necessary to mount it to work with properly configured properties. To do so, use the mount method. It will update the isMounted signal property.

Variable

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

if (viewport.mount.isAvailable()) {
  viewport.mount();
  viewport.isMounted(); // true
}

Functions

import {
  mountViewport,
  isViewportMounted,
} from '@telegram-apps/sdk';

if (mountViewport.isAvailable()) {
  mountViewport();
  isViewportMounted(); // true
}

To unmount, use the unmount method:

Variable

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

Functions

import {
  unmountViewport,
  isViewportMounted,
} from '@telegram-apps/sdk';

unmountViewport();
isViewportMounted(); // false

Binding CSS Variables

To expose the viewport 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 width, height and stableHeight into CSS variable names. By default, values are converted to kebab case with the prefix --tg-viewport-.

Variable

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

if (viewport.bindCssVars.isAvailable()) {
  viewport.bindCssVars();
  // Creates CSS variables like:
  // --tg-viewport-height: 675px
  // --tg-viewport-width: 320px
  // --tg-viewport-stable-height: 675px

  viewport.bindCssVars(key => `--my-prefix-${key}`);
  // Creates CSS variables like:
  // --my-prefix-height: 675px
  // --my-prefix-width: 320px
  // --my-prefix-stableHeight: 675px

  viewport.isCssVarsBound(); // true
}

Functions

import {
  bindViewportCssVars,
  isViewportCssVarsBound,
} from '@telegram-apps/sdk';

if (bindViewportCssVars.isAvailable()) {
  bindViewportCssVars();
  // Creates CSS variables like:
  // --tg-viewport-height: 675px
  // --tg-viewport-width: 320px
  // --tg-viewport-stable-height: 675px

  bindViewportCssVars(key => `--my-prefix-${key}`);
  // Creates CSS variables like:
  // --my-prefix-height: 675px
  // --my-prefix-width: 320px
  // --my-prefix-stableHeight: 675px

  isViewportCssVarsBound(); // true
}

Visibility

To track if mini app is visible, use isVisible signal. Invisible means app is collapsed or in another tab.

Variable

viewport.isVisible();

Functions

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

isVisible()

Expanding

To expand the viewport, use the expand method.

Variable

if (viewport.expand.isAvailable()) {
  viewport.expand();
}

Functions

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

if (expandViewport.isAvailable()) {
  expandViewport();
}

Fullscreen Mode

To enable the fullscreen mode, the method requestFullscreen is used:

Variable

if (viewport.requestFullscreen.isAvailable()) {
  await viewport.requestFullscreen();
  viewport.isFullscreen(); // true
}

Functions

import { requestFullscreen, isFullscreen } from '@telegram-apps/sdk';

if (requestFullscreen.isAvailable()) {
  await requestFullscreen();
  isFullscreen(); // true
}

To exit the fullscreen mode, use the exitFullscreen method:

Variable

if (viewport.exitFullscreen.isAvailable()) {
  await viewport.exitFullscreen();
  viewport.isFullscreen(); // false
}

Functions

import { exitFullscreen, isFullscreen } from '@telegram-apps/sdk';

if (exitFullscreen.isAvailable()) {
  await exitFullscreen();
  isFullscreen(); // false
}

Safe Area Insets

The viewport component offers access to two types of insets:

• Safe area insets
• Content safe area insets

For more details on the differences between these inset types, visit the Viewport page.

The component provides access to these insets through the following signals:

Variable

// Objects with numeric properties "top", "bottom", "left" and "right".
viewport.safeAreaInsets();
viewport.contentSafeAreaInsets();

// Numeric values.
viewport.safeAreaInsetTop();
viewport.safeAreaInsetBottom();
viewport.safeAreaInsetLeft();
viewport.safeAreaInsetRight();
viewport.contentSafeAreaInsetTop();
viewport.contentSafeAreaInsetBottom();
viewport.contentSafeAreaInsetLeft();
viewport.contentSafeAreaInsetRight();

Functions

import {
  viewportSafeAreaInsets,
  viewportSafeAreaInsetTop,
  viewportSafeAreaInsetBottom,
  viewportSafeAreaInsetLeft,
  viewportSafeAreaInsetRight,
  viewportContentSafeAreaInsets,
  viewportContentSafeAreaInsetTop,
  viewportContentSafeAreaInsetBottom,
  viewportContentSafeAreaInsetLeft,
  viewportContentSafeAreaInsetRight,
} from '@telegram-apps/sdk';

// Objects with numeric properties "top", "bottom", "left" and "right".
viewportSafeAreaInsets();
viewportContentSafeAreaInsets();

// Numeric values.
viewportSafeAreaInsetTop();
viewportSafeAreaInsetBottom();
viewportSafeAreaInsetLeft();
viewportSafeAreaInsetRight();
viewportContentSafeAreaInsetTop();
viewportContentSafeAreaInsetBottom();
viewportContentSafeAreaInsetLeft();
viewportContentSafeAreaInsetRight();