@telegram-apps/sdk-react@3

React.js package providing utilities that developers may find useful when developing a mini application.

TIP

Since this package offers utility functions that extend the functionality of @telegram-apps/sdk, it is recommended to review the SDK package documentation first.

Installation

Before proceeding, it is assumed that you have already installed the react package, as it is a peer dependency of this package.

pnpm

pnpm i @telegram-apps/sdk-react

npm

npm i @telegram-apps/sdk-react

yarn

yarn add @telegram-apps/sdk-react

INFO

This package fully re-exports the @telegram-apps/sdk package, so you don't need to install it separately.

Usage

Here is a simple usage example of the package:

index.tsx

import ReactDOM from 'react-dom/client';
import { init, backButton } from '@telegram-apps/sdk-react';

import { BackButton } from './BackButton.js';

// Initialize the package.
init();

// Mount the Back Button, so we will work with 
// the actual component properties.
backButton.mount();

ReactDOM
  .createRoot(document.getElementById('root')!)
  .render(<BackButton/>);

BackButton.ts

import { useEffect } from 'react';
import { backButton, useSignal } from '@telegram-apps/sdk-react';

/**
 * Component which controls the Back Button visibility.
 */
export function BackButton() {
  const isVisible = useSignal(backButton.isVisible);

  useEffect(() => {
    console.log('The button is', isVisible ? 'visible' : 'invisible');
  }, [isVisible]);

  useEffect(() => {
    backButton.show();
    return () => {
      backButton.hide();
    };
  }, []);

  return null;
}

Hooks

useLaunchParams

A hook that retrieves the application launch parameters. It works exactly as the retrieveLaunchParams function described in the @telegram-apps/bridge' s documentation.

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

function Component() {
  console.log(useLaunchParams());
  // {
  //   tgWebAppBotInline: false,
  //   tgWebAppData: {
  //     user: { ... },
  //     auth_date: Date(...),
  //     query_id: ...,
  //     hash: ...
  //   },
  //   ...
  // };
}

function Component2() {
  console.log(useLaunchParams(true));
  // {
  //   tgWebAppBotInline: false,
  //   tgWebAppData: {
  //     user: { ... },
  //     authDate: Date(...),
  //     queryId: ...
  //     hash: ...
  //   },
  //   ...
  // };
}

useRawLaunchParams

Returns launch parameters in a raw format from any known source.

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

function Component() {
  console.log(useRawLaunchParams());
  // tgWebAppBotInline=0&tgWebAppData=%7B%22user%22%3A%7B%7D...
}

useRawInitData

Uses the retrieveRawInitData function under the hood and allows retrieving the init data passed in its initial format.

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

function Component() {
  console.log(useRawInitData());
  // '{"user":...,"auth_date":...,"query_id":...,...}'
}

useSignal

A helper that allows a developer to use our signals in the application.

It returns the underlying value and updates it whenever the signal value changes.

import { useEffect } from 'react';
import { backButton, useSignal } from '@telegram-apps/sdk-react';

function Component() {
  const isVisible = useSignal(backButton.isVisible);

  useEffect(() => {
    console.log('The button is', isVisible ? 'visible' : 'invisible');
  }, [isVisible]);

  useEffect(() => {
    backButton.show();
    return () => {
      backButton.hide();
    };
  }, []);

  return null;
}

Migrating From v2 to v3

As long the package itself completely re-exports the @telegram-apps/sdk package, familiarize yourself with its own migration guide.

useLaunchParams behavior changed

As long as the underlying retrieveLaunchParams function was changed, the result of calling this hook was changed also. It now returns an object with launch parameters with their initially defined names (prefixed with the tgWebApp substring). So, make sure you are not using previous properties from the hook's result like themeParams, initData, etc.

The result now also doesn't contain the initDataRaw property, as long as it is not really a separate launch parameter. To extract raw init data use the useRawInitData hook instead.