A11y Element Focus Box

Link to A11y Element Focus Box copied to clipboard
Best Practice Impact - Moderate

A11y Element Focus Box looks for accessibility elements and ensures the accessibility path (VoiceOver's focus box) encapsulates the entire view. This rule will fail if the accessibility path is set and does not encapsulate the element's on-screen frame.

Impact

People using VoiceOver with sight are most impacted. VoiceOver will be announcing the details of one on-screen element, but the focus will appear partially or entirely off the element being announced.

Confirmation

  1. Turn on VoiceOver
  2. Focus the element
  3. One of the following will happen:
  • Inaccessible: VoiceOver's focus box will partially contain the element.
  • Inaccessible: VoiceOver's focus box will not contain the element at all.
  • Accessible: VoiceOver's focus box will fully contain the element.

How to Fix

UIKit

note

Requires the accessibility layer for accurate results. Learn how to load the accessibility layer here.

Incorrect usage of the accessibilityPath or accessibilityFrame on a view will result in this rule finding an issue. Fix in one of two ways:

  • Do not use accessibilityPath or accessibilityFrame. VoiceOver automatically calculates the on-screen coordinates of the view and should correctly draw a border (VoiceOver's focus box) around the currently-focused element. Using either of these accessibility APIs on an element will re-draw VoiceOver's focus box for that element.
  • If you must re-draw VoiceOver's focus box, ensure that you are correctly calculating the on-screen coordinates of the element and that you are recalculating and redefining the focus box every time the element moves (such as in a UIScrollView):
// Assuming we are in a ViewController
let button = UIButton()

// If not within a ViewController, self.view should be replaced with the rootView of the screen
let rootview = self.view
let onScreenFrame = button.superview!.convert(button.frame, to: rootview)
button.accessibilityPath = UIBezierPath(rect: onScreenFrame)

SwiftUI

This type of accessibility issue can no longer occur within SwiftUI views.