KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agent #developer-tools #codex #typescript #cli #deepseek-harness #claude-code #ai-agents #mcp #rust

mobile-viewport-control

★ 48 Open GitHub ↗

Dynamically control the mobile viewport

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

> <img src="https://stripe.dev/images/badges/archived.png" width="250">
>
> This project is inactive and is no longer being maintained.

# Mobile Viewport Control

This JavaScript library attempts to solve the hard problem of creating a
__[full-window modal]__ experience for mobile browsers.  The goal is to allow
it to be dropped into any page regardless of its viewport settings.  It does
this by attempting to control the mobile viewport and by hiding all elements
except the one you are trying to modalize.

[full-window modal]:http://uxmovement.com/mobile/why-you-should-avoid-using-modal-windows-on-mobile/

<table>
  <tr>
    <td>[![scroll][scroll-gif]][scroll-gfy]</td>
    <td>[![zoom][zoom-gif]][zoom-gfy]</td>
  </tr>
  <tr>
    <td>__Figure 1.__ Scrolling</td>
    <td>__Figure 2.__ Zooming + Scrolling</td>
  </tr>
</table>

__Background.__ The _viewport_ is the visible part of the webpage on your
screen (see quirksmode [[1]] [[2]]).  It is controlled by two things: _scroll_
and _zoom_.  The user can swipe to scroll and pinch to zoom. A JavaScript
developer can control the scroll programmatically, but there is no officially
supported method for controlling the _zoom_ programmatically.  However, we do
have a de facto standard for limiting and initializing the zoom:

[1]:http://www.quirksmode.org/mobile/viewports2.html
[2]:http://www.quirksmode.org/mobile/metaviewport/

```html
<head>
  <meta name="viewport" content="initial-scale=1">
  <meta name="viewport" content="minimum-scale=0">
  <meta name="viewport" content="maximum-scale=10">
</head>
```

__Workaround.__ There is an undocumented feature that allows us to modify the
viewport state at runtime by adding and modifying viewport tags.  There are
caveats depending on the browser.  The goal of this library is to identify and
workaround these caveats until there is a standard for programmatically
controlling zoom.  We have researched and tested on multiple platforms, though
we are currently focusing support for Mobile Safari and WebViews on iOS 7, 8, and 9.
(See __[Compatibility Testing](test/)__)

__Modals are the Use-Case.__ Viewport settings vary widely across different
webpages, making it hard to create drop-in modal experiences that work
everywhere (see [Stripe Checkout] and [Auth0 Lock]). For browsers that cannot
create pop-up tabs and for pages where redirection is not an option, this
library can help fill in the gaps.

> UPDATE: See the upcoming _[Payment Request API]_ for native mobile checkout modals for the web.

[Stripe Checkout]:https://stripe.com/checkout
[Auth0 Lock]:https://auth0.com/lock
[Payment Request API]:https://developers.google.com/web/updates/2016/07/payment-request

<table>
  <tr>
    <td>[![freeze][freeze-gif]][freeze-gfy]</td>
    <td>[![isolate][isolate-gif]][isolate-gfy]</td>
  </tr>
  <tr>
    <td>__Figure 3.__ Freezing and Thawing</td>
    <td>__Figure 4.__ Isolating the Modal</td>
  </tr>
 </table>

__The Abstraction.__ This library provides a limited abstraction for
controlling zoom: _freezing_ and _thawing_.  (See Figure 3). Freezing will lock
the zoom to a given scale.  Thawing will restore the viewport to what it was
before freezing, while also restoring the appropriate zoom limits (i.e. min and
max).  Thawing in this way is useful in the context of a modal.

__Isolating the Modal.__ The freeze/thaw functions are designed to be used in
conjunction with a third operation: _isolation_. (See Figure 4).  This is done
by passing an optional element ID to the freeze function, which you would
presumably wish to be the full-window modal.  This temporarily applies CSS
rules to ensure with high confidence that all elements except the given element
are collapsed (via `display:none`).  You can then style your element to fill
the window as a modal. Thawing will restore the page back to what it was
before.

## Usage

```
npm install mobile-viewport-control
```

```js
const viewport = require('mobile-viewport-control');
// ... or use `window.mobileViewportControl` if not used with package manager

// Freeze the viewport at a desired scale.
viewport.freeze(1.0, () => console.log('notified when frozen!'));

// Restore the viewport to what it was before freezing.
viewport.thaw(() => console.log('notified when thawed!'));
```

Additionally, to freeze the scroll area to a given element, you can pass an
element ID as the second argument.  We do this by temporarily hiding everything
else on the page.  Just make sure your element is a direct child of
`document.body`.

```js
viewport.freeze(1.0, 'myElementID');
```

## Testing

Please see __[Compatibility Testing](test/)__.

## License

[ISC License](LICENSE)

_Source code for the animated figures above: [mobile-viewport-control-viz](https://github.com/shaun-stripe/mobile-viewport-control-viz)_

[scroll-gif]:https://zippy.gfycat.com/EnchantedPowerfulIndri.gif
[scroll-gfy]:https://gfycat.com/EnchantedPowerfulIndri
[zoom-gif]:https://zippy.gfycat.com/InconsequentialImperturbableBuckeyebutterfly.gif
[zoom-gfy]:https://gfycat.com/InconsequentialImperturbableBuckeyebutterfly
[freeze-gif]:https://fat.gfycat.com/YearlyBitesizedBangeltiger.gif
[freeze-gfy]:https://gfycat.com/YearlyBitesizedBangeltiger
[isolate-gif]:https://fat.gfycat.com/MetallicFrighteningApisdorsatalaboriosa.gif
[isolate-gfy]:https://gfycat.com/MetallicFrighteningApisdorsatalaboriosa

mobile-viewport-control

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README