Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ryanve/verge
get viewport dimensions...detect elements in the viewport...trust in <!DOCTYPE html>
https://github.com/ryanve/verge
javascript responsive-design viewport viewport-dimensions
Last synced: 13 days ago
JSON representation
get viewport dimensions...detect elements in the viewport...trust in <!DOCTYPE html>
- Host: GitHub
- URL: https://github.com/ryanve/verge
- Owner: ryanve
- License: mit
- Created: 2012-05-30T16:21:23.000Z (over 12 years ago)
- Default Branch: master
- Last Pushed: 2022-03-02T02:13:54.000Z (over 2 years ago)
- Last Synced: 2024-05-16T15:04:22.826Z (6 months ago)
- Topics: javascript, responsive-design, viewport, viewport-dimensions
- Language: JavaScript
- Homepage: https://ryanve.dev/verge
- Size: 159 KB
- Stars: 694
- Watchers: 22
- Forks: 53
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
README
# verge
verge is a compact set of cross-browser viewport utilities written in native JavaScript. It includes the ability to detect if an element is in the current viewport. It works as a standalone module, an [ender](#ender) module, or as a [jQuery](#jquery) plugin. (npm: [verge](https://www.npmjs.org/package/verge))
## API
- .viewportW()
- .viewportH()
- .viewport() 1.8+
- .inViewport()
- .inX()
- .inY()
- .scrollX()
- .scrollY()
- .mq() 1.6+
- .rectangle()
- .aspect() 1.7+
#### Accuracy
- [Requires](https://github.com/ryanve/verge/issues/22#issuecomment-341944009) ``
- verge's viewport methods represent the [CSS viewport](http://www.w3.org/TR/CSS2/visuren.html#viewport): the [`@media (width)`](http://dev.w3.org/csswg/mediaqueries4/#width) and [`@media (height)`](http://dev.w3.org/csswg/mediaqueries4/#height) breakpoints.
- At certain zooms the viewport dimensions given by verge may be 1px off the expected `@media` value due to native rounding. For greater precision (at a slight speed tradeoff) consider [actual](https://github.com/ryanve/actual).
***
### .viewportW()
```js
verge.viewportW() // -> viewport width in pixels
```
### .viewportH()
```js
verge.viewportH() // -> viewport height in pixels
```
### .viewport()
Get both CSS viewport dimensions as an object with width and height properties.
```js
verge.viewportW() === verge.viewport().width // always true
verge.viewportH() === verge.viewport().height // always true
```
The [`.viewportW()`](#viewportw) syntax is slightly faster.
### .inViewport()
Test if any part of an element (or the first element in a matched set) is in the current viewport. Returns **boolean**.
```js
verge.inViewport(elem) // true if elem is in the current viewport
verge.inViewport(elem, 100) // true if elem is in the current viewport or within 100px of it
verge.inViewport(elem, -100) // true if elem is in the current viewport and not within 99px of the edge
```
#### Performance tip for sites that only scroll along **1** axis
```js
verge.inViewport(elem) === verge.inX(elem) && verge.inY(elem) // always true
```
##### Substitute [inViewport](#inviewport) with: [inY](#iny) on *vertical* sites, [inX](#inx) on *horizontal* ones.
- On pages without horizontal scroll, [inX](#inx) is always `true`.
- On pages without vertical scroll, [inY](#iny) is always `true`.
- If the viewport width is `>=` the `document` width, then [inX](#inx) is always `true`.
### .inX()
Test if any part of an element (or the first element in a matched set) is in the same x-axis section as the viewport. Returns **boolean**.
```js
verge.inX(elem) // true if elem is in same x-axis as the viewport (exact)
verge.inX(elem, 100) // true if elem is in same x-axis as the viewport or within 100px of it
verge.inX(elem, -100) // true if elem in is the viewport and not within 99px of the edge
```
### .inY()
Test if any part of an element (or the first element in a matched set) is in the same y-axis section as the viewport. Returns **boolean**.
```js
verge.inY(elem) // true if elem is in same y-axis as the viewport (exact)
verge.inY(elem, 100) // true if elem is in same y-axis as the viewport or within 100px of it
verge.inY(elem, -100) // true if elem in is the viewport and not within 99px of the edge
```
### .scrollX()
Get the horizontal scroll position in pixels. (Like [`window.scrollX`](https://developer.mozilla.org/en-US/docs/Web/API/Window.scrollX), but cross-browser.)
```js
verge.scrollX() // -> horizontal pixels scrolled
```
### .scrollY()
Get the vertical scroll position in pixels. (Like [`window.scrollY`](https://developer.mozilla.org/en-US/docs/Web/API/Window.scrollY), but cross-browser.)
```js
verge.scrollY() // -> vertical pixels scrolled
```
### .mq()
#### .mq(mediaQueryString)
Test if a [media query](http://airve.com/mq/) is active.
```js
verge.mq('(min-color:2)') // -> boolean
verge.mq('tv') // -> boolean
```
### .rectangle()
#### .rectangle(element, cushion?)
Get an a object containing the properties `top`, `bottom`, `left`, `right`, `width`, and `height` with respect to the top-left corner of the current viewport, and with an optional cushion amount. Its return is like that of the native [getBoundingClientRect](https://developer.mozilla.org/en/DOM/element.getBoundingClientRect).
The optional cushion parameter is an amount of pixels to act as a cushion around the element. If none is provided then it defaults to `0` and the rectangle will match the native rectangle. If a cushion is specified, the properties are adjusted according to the cushion amount. If the cushion is **positive** the rectangle will represent an area that is larger that the actual element. If the cushion is **negative** then the rectangle will represent an area that is **smaller** that the actual element.
```js
verge.rectangle(element) // rectangle object
verge.rectangle(element, 100) // rectangle object adjusted by 100 pixels
```
### .aspect()
#### .aspect(object?)
Get the aspect ratio of the viewport or of an object with width/height properties.
```js
verge.aspect() // -> viewport aspect ratio
verge.aspect(element) // -> element aspect ratio
verge.aspect(screen) // -> device aspect ratio
1 < verge.aspect() // => landscape orientation
```
## Integrate
### [jQuery](http://jquery.com)
```js
jQuery.extend(verge)
```
### [ender](https://github.com/ender-js)
```sh
ender build verge
```
## Contribute
Contribute by making edits in [`./src`](./src) or reporting [issues](../../issues).
```sh
npm install
npm test
```