ember-measure
Provides an easy to use mixin for measuring DOM elements within Ember Components,
and responding to size changes. Internally we use a ResizeObserver
, which is a new
type of MutationObserver
, as such there is an included polyfill to support older browsers back
to IE10.
Motivation
previously, you had to attach a listener to the document’s resize event to get notified of any change of the viewport’s dimensions. In the event handler, you would then have to figure out which elements have been affected by that change and call a specific routine to react appropriately. If you need the new dimensions of an element after a resize, you need to call getBoundingClientRect or getComputerStyle, which can cause layout thrashing if you don’t take care of batching all your reads and all your writes.
And then you realize that this doesn’t even cover the cases where elements change their size without the main window having been resized. For example, appending new children, setting an element’s display style to none, or similar actions can change the size of an element, its siblings or ancestors.
This is why ResizeObserver is a useful primitive. It reacts to changes in size of any of the observed elements, independent of what caused the change. It provides you access to the new size of the observed elements, too. Let’s get straight into it.
This addon is semantically similar to souporserious/react-measure and borrows some implementation ideas from there.
Installation
ember install ember-measure
Requirements:
- Node 6+
- Ember 2.10+
- Ember CLI 2.10+
Usage
You can use this addon in two ways:
1. As a component:
{{dom-measure as |rect|}} <p>I am {{rect.client.height}}px tall!</p>{{/dom-measure}}
2. Within a component:
;; ;
There's also a contentRect
property which is updated whenever a change is made.
You could, for example, use this to fetch the width
and height
of the element:
;;; ;
contentRect
The contentRect
has the following properties:
contentRect.client
:
Contains the measurements of this component.
contentRect.offset
:
Contains the offset position of this component from the document.
contentRect.scroll
:
Contains the scroll offset information.
contentRect.bounds
:
Uses getBoundingClientRect
to calculate bounds of the component element. You can disable this property
by supplying a custom list of rectTypes
.
contentRect.margin
:
Uses getComputedStyle
to calculate margins of the component element. You can disable this property (to avoid layout thrashing)
by supplying a custom list of rectTypes
.
contentRect.entry
Contains the ResizeObserverEntry
for the current resize event, which can be further
queried for more size information.
rectTypes
You can control which properties are measured when a resize occurs by supplying
your own list of rectTypes
within the Component.
Defaults to ['client', 'offset', 'scroll', 'bounds', 'margin']
.
Take a look at the dummy app for a working example.
Caviates
The Polyfill used by this library doesn't observe SVG changes correctly. To work around this, put the SVG you want to measure inside a DIV and measure the div, then use the observerd measurements to fill the SVG width and height to match the DIV.
Running
ember serve
- Visit your app at http://localhost:4200.
Running Tests
npm test
(Runsember try:each
to test your addon against multiple Ember versions)ember test
ember test --server
Building
ember build
For more information on using ember-cli, visit https://ember-cli.com/.