@vkruglikov/react-telegram-web-app

The library provides access to the initialization data passed by Telegram.

InitDataUnsafe

This object contains the raw data from the Telegram WebApp initialization. Key fields include:

• user: A WebAppUser object containing user details (id, first_name, username, etc.).
• chat: A WebAppChat object if the app is launched from a chat.
• auth_date: The timestamp of the data.
• hash: The validation hash.
• query_id: The unique query ID.
• start_param: The start parameter used to launch the app.

InitData

InitData is the raw string representation of the initialization data.

To run the demo locally with HTTPS (required for many Telegram Mini App features), use mkcert to generate a certificate for your local domain.

1. Run the following command to create a certificate:

   mkcert react-telegram-web-app.domain

2. Map the domain to your local machine by adding it to your /etc/hosts file:

   127.0.0.1 react-telegram-web-app.domain

To use this library, follow these steps:

1. Initialize your Web App: Ensure you have followed the Telegram Web App initialization steps as the package depends on the Telegram Web App context.
2. Install the package: Run the following command in your project directory. Note that the library currently supports React ^18.

npm i @vkruglikov/react-telegram-web-app --save

When using WebAppProvider, you can pass an Options object to customize behavior.

This example demonstrates how to use MainButton and the useShowPopup hook together to trigger a native Telegram popup when a button is clicked.

import { MainButton, useShowPopup } from '@vkruglikov/react-telegram-web-app';

const Content = () => {
  const showPopup = useShowPopup();

  const handleClick = () =>
    showPopup({
      message: 'Hello, I am popup',
    });

  return <MainButton text="SHOW POPUP" onClick={handleClick} />;
};

The useShowPopup hook provides a function to display a native Telegram popup.

Returns: ShowPopupFunction which accepts ShowPopupParams.

import { useShowPopup } from '@vkruglikov/react-telegram-web-app';

const showPopup = useShowPopup();

showPopup({ message: 'Hello world' }).then(buttonId => console.log(buttonId));

The useInitData hook provides access to the Telegram initialization data.

Returns a tuple containing:

• initDataUnsafe: undefined | InitDataUnsafe
• initData: undefined | string (the raw init data string)

import { useInitData } from '@vkruglikov/react-telegram-web-app';

const [initDataUnsafe, initData] = useInitData();

The useCloudStorage hook provides access to the Telegram CloudStorage object using Promise-based functions, eliminating the need to manually pass callbacks. It allows you to persist data in the user's Telegram cloud.

Returns an object containing:

• getItem: GetItemFunction
• getItems: GetItemsFunction
• getKeys: GetKeysFunction
• removeItem: RemoveItemFunction
• setItem: SetItemFunction

// Note: Specific implementation details for GetItemFunction etc. are in their respective documentation
const { getItem, setItem } = useCloudStorage();

The MainButton component accepts the following props to control the Telegram MiniApp's main action button:

<MainButton
  text="Submit"
  color="#ff0000"
  textColor="#ffffff"
  disabled={false}
  progress={false}
  onClick={() => console.log('Button clicked!')}
/>