twa-dev/sdk

For React projects, the SDK provides specialized components that simplify interacting with Telegram Web App elements. Instead of calling imperative methods on the WebApp object, you can use declarative components.

Available React components include:

• MainButton
• SecondaryButton
• BottomBar
• BackButton

Instead of relying on the global window.Telegram.WebApp object provided by the Telegram script, you can import WebApp directly from the package. This allows for a cleaner, module-based development workflow with full TypeScript support.

import WebApp from '@twa-dev/sdk'

WebApp.showAlert('Hey there!');

Install the @twa-dev/sdk package to use the Telegram Web Apps (TWA) SDK as a modern npm module instead of using the traditional <script> tag approach. This package provides TypeScript support.

npm i @twa-dev/sdk

To use the BackButton React component and other TWA SDK features, install the @twa-dev/sdk package via npm.

npm i @twa-dev/sdk

The MainButton component provides a declarative React wrapper for the imperative Telegram Web Apps MainButton SDK. Instead of manually calling methods like .setText() or .show(), you can use the component with props that correspond to the underlying SDK methods.

import { MainButton } from '@twa-dev/sdk/react';

<MainButton text="Submit" onClick={() => alert('submitted')} />

The @twa-dev/sdk/react package provides a declarative React component wrapper for the imperative Telegram Web Apps (TWA) BackButton SDK. Instead of manually calling BackButton.show() and BackButton.onClick(), you can use the <BackButton /> component and pass an onClick handler.

import { BackButton } from '@twa-dev/sdk/react';

// Inside your component
<BackButton onClick={() => window.history.back()} />

The BottomBar component provides a declarative React wrapper for the imperative Telegram Web Apps bottom bar SDK. It acts as a container for MainButton and SecondaryButton components. Instead of calling window.Telegram.WebApp.setBottomBarColor manually, you can control the bottom bar appearance using the bgColor prop.

import { BottomBar, MainButton, SecondaryButton } from '@twa-dev/sdk/react';

<BottomBar bgColor="#ff0000">
  <MainButton text="Continue" onClick={() => alert('continue')} />
  <SecondaryButton text="Cancel" position="bottom" onClick={() => alert('cancelled')} />    
</BottomBar>

The SecondaryButton component is a React wrapper for the imperative Telegram Web App SecondaryButton SDK. It allows you to control the TWA Secondary Button using a declarative React pattern instead of calling imperative methods like .setParams(), .show(), and .onClick() manually.

import { MainButton, SecondaryButton } from '@twa-dev/sdk/react';

<MainButton text="Continue" onClick={() => alert('continue')} />
<SecondaryButton text="Cancel" position="bottom" onClick={() => alert('cancelled')} />

The BottomBar component accepts the following props, which correspond to the underlying TWA SDK properties and methods:

- children
- bgColor

The SecondaryButton component accepts the following props, which correspond directly to the underlying TWA SDK properties and methods:

- `text`
- `color`
- `textColor`
- `disabled`
- `progress`
- `onClick`
- `hasShineEffect`
- `position`

The MainButton component accepts the following props, which correspond to the Telegram Web Apps SDK properties and methods:

- text
- color
- textColor
- disabled
- progress
- onClick
- hasShineEffect