NeuroAgent

How to disable bounce effect in Telegram WebApp fullscreen mode

Complete guide to preventing bounce effect in Telegram WebApp. Use disableVerticalSwipes() API for proper operation without side effects.

#bounce-effect#disable-vertical-swipes#fullscreen-mode#react-telegram#telegram-api#telegram-webapp

How to prevent website bounce in Telegram WebApp fullscreen mode?

I’m creating a Telegram WebApp with React and have encountered an issue: in fullscreen mode, the website can be pulled up and down from the top and bottom, causing a bounce effect.

What has already been attempted:

  • Calling Telegram API methods: tg.expand(), tg.disableVerticalSwipes(), tg.requestFullscreen()
  • Applying CSS styles to body: position: fixed; inset: 0;

The problem: The CSS styles help prevent the bounce, but create a new bug - the site stops responding to clicks after attempting to pull the page.

Question: How can I completely prevent vertical pulling of the website in Telegram WebApp without causing side effects? Are there special Telegram API methods or hacks to modify this behavior?

NeuroAgent

Preventing Bounce Effect in Telegram WebApp

To prevent the bounce effect in fullscreen Telegram WebApp, you need to use the disableVerticalSwipes() method from the Telegram API, which was added in BOT API version 7.7. This method is specifically designed to block unwanted vertical swipes that cause bouncing and doesn’t cause problems with click handling, unlike CSS solutions with position: fixed.

Table of Contents

Basic Solution via Telegram API

The main and most reliable solution is to use the disableVerticalSwipes() method, which was added to the Telegram WebApp API in version 7.7. This method completely disables vertical swipes that cause the bounce effect.

javascript
// Call the method after initializing WebApp
Telegram.WebApp.disableVerticalSwipes();

This method has several advantages:

  • Doesn’t affect click handling - unlike CSS solutions
  • Specifically designed for Telegram - takes into account platform-specific features
  • Simple implementation - doesn’t require complex configurations

Important: the disableVerticalSwipes() method is only available in Telegram WebApp version 7.7 and higher. Most modern versions of Telegram already support this functionality.

Implementation in React Applications

In React applications, there are several ways to correctly implement this solution:

1. Direct Use of Telegram WebApp

javascript
import { useEffect } from 'react';

function TelegramWebApp() {
  useEffect(() => {
    // Check if we're in Telegram WebApp
    if (window.Telegram && window.Telegram.WebApp) {
      const tg = window.Telegram.WebApp;
      
      // Expand WebApp to fullscreen
      tg.expand();
      
      // Disable vertical swipes
      tg.disableVerticalSwipes();
      
      // Request fullscreen mode
      tg.requestFullscreen?.();
    }
  }, []);

  return (
    <div className="app-container">
      {/* Your app */}
    </div>
  );
}

2. Using the @vkruglikov/react-telegram-web-app Library

A more convenient approach is to use a specialized React library:

javascript
import { WebAppProvider, useTelegramWebApp } from '@vkruglikov/react-telegram-web-app';
import { useEffect } from 'react';

function AppContent() {
  const tg = useTelegramWebApp();
  
  useEffect(() => {
    if (tg) {
      tg.expand();
      tg.disableVerticalSwipes();
      tg.requestFullscreen?.();
    }
  }, [tg]);

  return (
    <div className="app">
      {/* Your app */}
    </div>
  );
}

function App() {
  return (
    <WebAppProvider>
      <AppContent />
    </WebAppProvider>
  );
}

This library provides:

  • Context for accessing Telegram WebApp
  • Components for managing buttons and other elements
  • Hooks for convenient work with the API

Alternative Methods and Their Problems

Problems with CSS Solutions

As you’ve already discovered, the CSS approach with position: fixed creates problems:

css
body {
  position: fixed;
  inset: 0;
  overflow: hidden;
}

Main problems with CSS solutions:

  • Event handling is disrupted - clicks stop working after swiping
  • Scrolling issues - internal content scrolling may stop working
  • Doesn’t comply with Telegram recommendations - may conflict with native behavior

Outdated Methods

Previously, complex workarounds were used to solve this problem, for example:

javascript
// Outdated method, no longer recommended
document.addEventListener('touchmove', (e) => {
  e.preventDefault();
}, { passive: false });

Such approaches have many side effects and are not recommended for use.

CSS Setup for Compatibility

Even when using disableVerticalSwipes(), some CSS settings can improve the user experience:

css
.app-container {
  height: 100vh;
  width: 100vw;
  overflow: hidden;
  -webkit-overflow-scrolling: touch;
}

/* To prevent accidental selections during swipes */
.app-container * {
  -webkit-user-select: none;
  user-select: none;
}

/* For proper scrolling inside content */
.scrollable-content {
  height: 100%;
  overflow-y: auto;
  -webkit-overflow-scrolling: touch;
}

Checking WebApp Readiness

It’s important to ensure that Telegram WebApp is fully ready before calling methods:

javascript
useEffect(() => {
  const initTelegram = async () => {
    if (window.Telegram && window.Telegram.WebApp) {
      const tg = window.Telegram.WebApp;
      
      // Wait for WebApp to be ready
      tg.ready();
      
      // Check API version
      console.log('WebApp version:', tg.version);
      
      // Expand and configure
      tg.expand();
      tg.disableVerticalSwipes();
      
      // Show that the app is ready
      tg.MainButton.setText('Ready');
      tg.MainButton.show();
    }
  };
  
  initTelegram();
}, []);

Full Implementation Example

Here’s a complete React component example with proper Telegram WebApp setup:

javascript
import { useEffect, useState } from 'react';
import { WebAppProvider, useTelegramWebApp } from '@vkruglikov/react-telegram-web-app';

function TelegramAppComponent() {
  const tg = useTelegramWebApp();
  const [isReady, setIsReady] = useState(false);

  useEffect(() => {
    if (tg && !isReady) {
      // Configure WebApp
      tg.ready();
      tg.expand();
      tg.disableVerticalSwipes();
      
      // Configure MainButton
      tg.MainButton.setText('Close');
      tg.MainButton.onClick(() => {
        tg.close();
      });
      tg.MainButton.show();
      
      setIsReady(true);
    }
  }, [tg, isReady]);

  if (!isReady) {
    return <div>Loading...</div>;
  }

  return (
    <div className="telegram-app">
      <h1>My App in Telegram</h1>
      <p>Bounce disabled via disableVerticalSwipes()</p>
      
      <div className="content">
        {/* Your content here */}
      </div>
    </div>
  );
}

// Wrapper for the entire app
function TelegramApp() {
  return (
    <WebAppProvider>
      <TelegramAppComponent />
    </WebAppProvider>
  );
}

export default TelegramApp;

Testing and Debugging

When testing, ensure that:

  1. Telegram version is checked - the disableVerticalSwipes() method is available in version 7.7+
  2. Correct sequence of calls - first ready(), then expand(), then disableVerticalSwipes()
  3. Error handling - add a check for the existence of the Telegram.WebApp object
javascript
useEffect(() => {
  try {
    if (!window.Telegram?.WebApp) {
      console.warn('Telegram WebApp not found');
      return;
    }
    
    const tg = window.Telegram.WebApp;
    
    if (typeof tg.disableVerticalSwipes !== 'function') {
      console.warn('disableVerticalSwipes not available in this version');
      return;
    }
    
    tg.ready();
    tg.expand();
    tg.disableVerticalSwipes();
    
  } catch (error) {
    console.error('Error initializing Telegram WebApp:', error);
  }
}, []);

Sources

  1. Telegram Mini Apps - Official Documentation
  2. How to Fix The Telegram Mini App Scrolling Collapse Issue - DEV Community
  3. How to disable closing telegram web app by swiping down - Stack Overflow
  4. A bug with collapsing when scrolling in Web App for Telegram Bot - Stack Overflow
  5. React components for Telegram Mini Apps - GitHub

Conclusion

  1. Main solution - use the Telegram.WebApp.disableVerticalSwipes() method to prevent the bounce effect without side effects.

  2. Correct sequence - call methods in this order: ready(), expand(), disableVerticalSwipes(), requestFullscreen().

  3. React integration - for convenience, use the @vkruglikov/react-telegram-web-app library or implement a hook to access Telegram WebApp.

  4. Avoid CSS hacks - methods like position: fixed and overflow: hidden cause problems with event handling and are not recommended.

  5. Version check - ensure your Telegram version supports the disableVerticalSwipes() method (available since version 7.7).

Applying these recommendations will completely eliminate the bounce problem in your Telegram WebApp on React without causing side effects with event handling.

How to check Telegram WebApp version to use disableVerticalSwipes()?What alternative methods exist for preventing bounce in Telegram WebApp?How to properly initialize Telegram WebApp in React application?What CSS styles are compatible with disableVerticalSwipes() in Telegram WebApp?How to handle errors when initializing Telegram WebApp?How to configure scrolling inside content after disabling vertical swipes?
Ask NeuroAgent