Skip to content


JavaScript library to help modern web applications with accessibility concerns by making accessibility simpler

# ally.when.focusable

Executes a callback once an element fulfills and is visible in the viewport

# Description

Element.focus() scrolls the element into view if it isn't already. In situations where content is not revealed immediately, but through a transition or animation this can be a problem if the element is focused to early.

The callback executes once the predicates, 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. Waiting for the callback to execute is aborted automatically should another element have gotten focus prior to the context element coming fully into view. The callback is executed immediately if the context element is already fully visible and focusable.

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.focusable({
  context: '#element-to-focus',
  callback: function(element) {


# 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

# 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

# ally.when.focusable Example

ally.when.focusable Example on

play with ally.when.focusable Example on or open the document of ally.when.focusable Example

# Notes

This method may cause layout thrashing.

# Contributing