visible-area.md

layout	tags
doc-api.html	service, argument-object

ally.when.visibleArea

Executes a callback once an element is visible in the viewport

Description

The callback is executed once the predicates ally.is.visible and ally/util/visible-area return positive. Visibility detection works regardless of the technical way an element was made invisible. The predicates are evaluated on every animation frame.

The callback function executes exactly once, meaning the callback won't execute every time the element comes into view. The callback is executed immediately if the context element is already fully visible.

The callback may return false to indicate that another predicate (handled by the callback function) has not been fulfilled yet and the callback should be executed again on the next animation frame.

Usage

var handle = ally.when.visibleArea({
  context: '#element-to-focus',
  callback: function(element) {
    console.log('element is visible', element);
  },
});

handle.disengage();

Arguments

Name	Type	Default	Description
context	<selector>	required	The element to observe. The first element of a collection is used.
callback	function	required	The callback to execute when context element is visible in viewport and focusable. See Callback Signature for details.
area	number	1	The percentage (0 - 1) of area of the context element has to be visible in the viewport.

Returns

A <service> interface, providing the handle.disengage() method to stop the service.

Throws

• TypeError if context option is not specified or not a HTMLElement.
• TypeError if callback option is not specified or not a function.

Callback signature

The callback is invoked with one argument, the HTMLElement identified by context. The callback can return false to signal that the service needs to keep observing context, to allow additional state verification to be performed within the callback. If nothing is returned, the service disengages after the callback finished processing.

Examples

@@@example /api/when/visible-area.example.html

visibleArea example

@@@

Changes

• As of v1.3.0 the callback is always executed asynchronously.

Notes

:::note This method may cause layout thrashing. :::

Related resources

• Managing focus in animated UI

Contributing

• module source
• document source
• unit test