Update:
After the recent update to Telegram in version BOT API 7.7, the methods enableVerticalSwipes and disableVerticalSwipes should be used instead for solving this issue, making the below workarounds unnecessary.
https://core.telegram.org/bots/webapps#july-7-2024
Note: I was supposed to update this article with a new method due to some bugs it had, but unfortunately, I haven't had the time yet. However, based on some existing trend mini-apps, I devised a better trick to prevent the mini-app from closing and control this issue. a sample web app that uses this new trick for fixing this issue is available to check out here: (Demo Mini App). Also, I have provided the code snippets for this mini app in this Github gist.
The logic and explanations in this article remain valid and applicable.
Introduction
Telegram Mini Apps empower developers to create dynamic interfaces using JavaScript directly within the platform. However, on touchscreen devices, users frequently encounter unexpected collapses or scrolling issues while interacting with these Mini Apps, significantly impacting the overall user experience.
Visual Comparsion:
Before diving into discussing why it's happening and the solution for it, let's visually observe the problem.
 |
 |
|---|---|
| Bug: Swiping down the Telegram Mini App causes it to collapse instead of scrolling | Fixed: Swiping down the Telegram Mini App now correctly scrolls through the content after the issue is fixed! |
Why It Happens
The scrolling collapse occurs when the document inside the Telegram Mini App is either not scrollable (with a height equal to the viewport) or scrollable but not scrolled (where the scrollY of the window object equals zero). In such instances, swiping down is interpreted as a command to collapse the document, reducing its size.
Now let's proceed to implement the solution. I'll provide a step-by-step guide to resolve the problem.
Step-by-Step Solution:
Step 1: Ensure the Document is Scrollable:
Firstly, it's essential to ensure that the document is scrollable. We achieve this by checking if the document's scroll height is greater than the viewport height. If not, we adjust the document's height accordingly.
// Ensure the document is scrollable
function ensureDocumentIsScrollable() {
const isScrollable =
document.documentElement.scrollHeight > window.innerHeight;
// Check if the document is scrollable
if (!isScrollable) {
/*
Set the document's height to 100 % of
the viewport height plus one extra pixel
to make it scrollable.
*/
document.documentElement.style.setProperty(
"height",
"calc(100vh + 1px)",
"important"
);
}
}
// Call ensureDocumentIsScrollable function when the entire page has loaded.
window.addEventListener("load", ensureDocumentIsScrollable);
Step 2: Prevent window.scrollY from Becoming Zero
Next, we prevent window.scrollY from becoming zero when swiping down on the scrollable element. This prevents unexpected collapses when swiping down.
// Prevent windwo.scrollY from becoming zero
function preventCollapse(event) {
if (window.scrollY === 0) {
window.scrollTo(0, 1);
}
}
// Attach the above function to the touchstart event handler of the scrollable element
const scrollableElement = document.querySelector(".scrollable-element");
scrollableElement.addEventListener("touchstart", preventCollapse);
Now that we've outlined the steps, let's integrate the solution into your code. Below is the full code snippet. I've removed unnecessary code and styles to understand the code better.
<html>
<head>
<style>
.scrollable-element {
overflow-y: scroll;
height: 32rem;
font-size: 6.25rem;
border: 1px solid;
}
</style>
</head>
<body>
<div class="scrollable-element">
<div>Item 1</div>
<div>Item 2</div>
<div>Item 3</div>
<div>Item 4</div>
<div>Item 5</div>
<div>Item 6</div>
<div>Item 7</div>
<div>Item 8</div>
<div>Item 9</div>
<div>Item 10</div>
</div>
<script>
function ensureDocumentIsScrollable() {
const isScrollable =
document.documentElement.scrollHeight > window.innerHeight;
if (!isScrollable) {
document.documentElement.style.setProperty(
"height",
"calc(100vh + 1px)",
"important"
);
}
}
function preventCollapse() {
if (window.scrollY === 0) {
window.scrollTo(0, 1);
}
}
const scrollableElement = document.querySelector(".scrollable-element");
scrollableElement.addEventListener("touchstart", preventCollapse);
window.addEventListener("load", ensureDocumentIsScrollable);
</script>
</body>
</html>
By implementing these adjustments, your Telegram Mini App will no longer suffer from unexpected collapses when scrolling for swiping down.
I encourage you to deploy the provided code for a Telegram Web App and observe the results firsthand.
Additionally, you can experience the fix in action on a Telegram Mini App I've applied this solution to: @theme_inspector_bot
Top comments (9)
After the latest update in telegram (collapsed apps) now when expanding the app to full screen, this solution stopped working for me. Any suggestions how this can be fixed?
Video: vimeo.com/978230725
You no longer need this solution. Instead, you can use the new function
disableVerticalSwipes()introduced in version 7.7 of the BOT API.BotNews
TMA Docs
Does it work for you on ios? I still have an old behavior
This feature is available in version 7.7+. However, most versions are currently 7.6, and no update for Telegram has been released yet. I think these changes will be implemented in the next update of the Telegram app for iOS and Android, and version 7.7 will become available.
Is it working now on ios?.. Because in iOS it is still having the issue in my telegram mini app.In android it is fixed.
Thanks, that's a huge win!
how to use it
This is a good solution, but I found a bug. You can watch an example video here: vimeo.com/951274267?share=copy.
Sometimes when I try to scroll up, the content flickers.
thanks for pointing that out and sharing the video! I did notice that flickering bug and also saw that the page stretches, which is another issue. I'll update the post with a fix or a better solution soon, but I'm a bit busy right now. I'll get to it as soon as I can. thanks again for your help!