Skip to content

Viewport

Implements Telegram Mini Apps viewport functionality.

Initialization

To initialize the component, use the initViewport function:

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

const [viewport] = initViewport();

INFO

Since Viewport can't be instantiated synchronously, this function returns a promise as the first value in the tuple that will be resolved when the actual viewport state is retrieved.

Dimensions

The application can display just the top part of the Mini App, with its lower part remaining outside the screen area. From this position, the user can "pull" the Mini App to its maximum height, while the developer can do the same by calling expand method (use isExpanded prop to get current expansion state):

typescript
const [viewport] = initViewport();

const vp = await viewport;

if (!vp.isExpanded) {
    vp.expand(); // will expand the Mini App, if it's not
}

As the position of the Mini App changes, the current height value of the visible area will be updated in real time.

INFO

Please note that the refresh rate of this value (height) is not sufficient to smoothly follow the lower border of the window. It should not be used to pin interface elements to the bottom of the visible area. It's more appropriate to use the value of the stableHeight field for this purpose.

Requesting Actual Data

To get actual viewport information, developer could use requestViewport function:

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

requestViewport().then((data) => {
    // Output:
    // { height: 122, isExpanded: false, width: 375, isStateStable: true }
    console.log(data);
});

Events

List of events, which could be tracked:

EventListenerTriggered when
change() => voidSomething in component changed
change:height(height: number) => voidheight property changed
change:isExpanded(isExpanded: boolean) => voidisExpanded property changed
change:stableHeight(stableHeight: boolean) => voidstableHeight property changed
change:width(width: boolean) => voidwidth property changed

Released under the MIT License.