api

layout
doc-page.html

API index

When creating web applications or UI widgets these modules may come in handy.

Countering browser bugs

Every software has its problems - so do browsers. These utilities combat things browsers get wrong.

• ally.fix.pointerFocusChildren (Internet Explorer 10 - 11)
• ally.fix.pointerFocusInput (Safari and Firefox on Mac OS X)
• ally.fix.pointerFocusParent (WebKit and old Blink)

Extended :focus Styling

Sometimes :focus is not enough for communicating your application's intentions properly.

• ally.style.focusSource provides html[focus-source="pointer|key|script"]
• ally.style.focusWithin polyfills :focus-within with .ally-focus-within

Altering browser focus behavior

While it's best to use standardized features and leave browsers to figure things out, specifications sometimes leave us hanging in limbo.

• ally.maintain.disabled renders elements inert to prevent any user interaction
• ally.maintain.hidden sets aria-hidden="true" on insignificant branches
• ally.maintain.tabFocus traps TAB focus in the tabsequence

Finding elements

In order to work with focusable elements, we must first know which elements we're supposed to work with. See what does "focusable" mean? for a differentiation.

• ally.query.firstTabbable finds the first keyboard focusable element
• ally.query.focusable finds all focusable elements
• ally.query.shadowHosts finds all elements hosting a ShadowRoot
• ally.query.tabbable finds all keyboard focusable elements in DOM order
• ally.query.tabsequence finds all keyboard focusable elements in Sequential Navigation Focus Order

Element state

Unlike any other ally modules, these components do not take take options.context argument, but expect the element as first argument, allowing easy use in .filter(). See what does "focusable" mean? for a differentiation.

• ally.is.activeElement returns true if the element is the activeElement of its host context, i.e. its document, iFrame or ShadowHost
• ally.is.disabled returns true if the element is :disabled
• ally.is.focusRelevant returns true if the element is considered theoretically focusable
• ally.is.focusable returns true if the element is considered focusable by script
• ally.is.onlyTabbable returns true if the element is tabbable but not focusable
• ally.is.shadowed returns true if the element is the descendant of a ShadowRoot
• ally.is.tabbable returns true if the element is considered keyboard focusable ("tabbable")
• ally.is.validArea returns true if the <area> element is properly used via <map> by an <img>
• ally.is.validTabindex returns true if the element's tabindex attribute value is sound
• ally.is.visible returns true if the element is rendered (but not necessarily visible in the viewport)

Manipulating element state

Making up for missing or lacking DOM mutation APIs.

• ally.element.blur shifts focus away from an element
• ally.element.disabled disables all elements, not only form controls
• ally.element.focus shifts focus to an element

Reacting to element state

Especially when dealing with transitional user interfaces we need to know when an element can be safely focused.

• ally.when.focusable executes a callback once an element fulfills ally.is.focusable and is visible in the viewport
• ally.when.key executes a callback when a given key has been pressed
• ally.when.visibleArea executes a callback once an element is visible in the viewport

DOM traversal

Sometimes you need some DOM traversal utilities

• ally.get.insignificantBranches returns an array containing the branches of the DOM that do contain any of the target elements
• ally.get.activeElement identifies the element that has focus

Values

• ally.map.attribute maps WAI-ARIA states and properties
• ally.map.keycode maps control keys to readable names

---

Developer modules

When creating libraries these modules may come in handy.

:::note When you find yourself using one of these in your application code, we should talk about what you're trying to achieve and how we could do that as part of the library instead. Get in touch, file an issue explaining what you're trying to achieve! :::

DOM traversal (extended)

Sometimes you need some DOM traversal utilities

• ally.get.activeElements identifies the ShadowHost ancestry of the active element
• ally.get.insignificantBranches
• ally.get.focusRedirectTarget
• ally.get.focusTarget
• ally.get.parents
• ally.get.shadowHostParents
• ally.get.shadowHost

Event dispatchers

Emitting events when there's no standardized equivalent

• ally.event.activeElement
• ally.event.shadowFocus

Event listeners

Translate volatile events to stateful interfaces

• ally.observe.interactionType observes user interaction method to distinguish pointer and keyboard actions
• ally.observe.shadowMutations registers MutationObservers across nested ShadowRoots

---

Contributor modules

When working on ally.js these modules may come in handy.

:::note When you find yourself using one of these in your application or library code, we should talk about what you're trying to achieve and how we could do that as part of the library instead. Get in touch, file an issue explaining what you're trying to achieve! :::

::note These modules are only available to be consumed via ES6, AMD or CommonJS directly, they are not exposed in the production bundle dist/ally.min.js. :::

The internal tools are documented in a less accessible way to make it just a tiny bit harder for someone not working on ally to use them. This is intentional. The stability of these APIs is not guaranteed.

• ally/prototype/*
• ally/selector/*
• ally/supports/*
• ally/util/*