Active Control Name

What We Check For

An interactive element should have an accessible name available for assistive technologies such as VoiceOver and Voice Control.

Failing Example ❌

No name (accessibilityLabel) set.

VoiceOver reads "Button"

Voice Control — user speaks "Notifications"
Element does not respond since it has no name

Passing Example ✅

accessibilityLabel=
'Notifications'

VoiceOver reads "Notifications, button"

Voice Control — user speaks "Notifications"
Element activates because its name matches

At a Glance

• This rule has a critical impact for users
• Every interactive element needs a name: buttons, links, and inputs all require an accessible name that VoiceOver can announce
• If an interactive element has no visible text, provide one explicitly using accessibilityLabel to give it a meaningful name
• Don't leave VoiceOver with nothing to say: an element that announces only its role or value - with no name - doesn't give users accurate context for what it does
• VoiceOver will try to announce something (such as the text of the button or image name), so it is best to provide an accurate and intentional name

Impact to Users

People using VoiceOver are most impacted. An interactive element without a name will not relay the full context or purpose to the person interacting with it.

When an interactive element - such as a button, form element, or custom control - does not have an accessible name, VoiceOver has nothing to announce when this element is focused. For example, you might have a button with an image of an underlined arrow indicating the user can download. Without an accessible name, VoiceOver will only announce "Button, double-tap to activate."

This rule also has an impact for people who are using Voice Control. Voice Control users who try to activate the element by speaking its visible label will find that it doesn’t respond.

Confirm Active Control Name Issue

1. Turn on VoiceOver
2. Focus the interactive element
3. One of the following will happen:
   • Inaccessible: It will not announce its name, only its role and value if present.
   • Accessible: It will announce its name in VoiceOver.

Fix Issues

To resolve Active Control issues, add an accessibility label to each interactive element so VoiceOver has a meaningful name to announce. Ensure the name you select contains the visible label of the element.

Ensure the name you select describes the action, not the appearance. An icon of a magnifying glass should be labeled “Search,” not “magnifying glass icon.”

If an element’s purpose changes based on state (e.g. a Play/Pause button), update the name whenever the state changes.

UIKit

To fix an issue found by this rule, add an accessibilityLabel to the control.

button.accessibilityLabel = "Deque Systems Website"

SwiftUI

Ensure the element's text is meaningful or provide an accessibilityLabel if more context is needed.

Use case: Button with an image for its label

Ensure the image has a meaningful name. Know that this won't be an option when supporting multiple languages. If the name isn't viable, set an accessibilityLabel on the image.

Alternatively, combine a parent element (ex: generic wrapper) and its children (ex: text and a button) to make one element. If meaningful text isn't available, set an accessibilityLabel on the entire view as shown below.

var body: some View {
    HStack(alignment: .center, spacing: 10,
           content: {
        Text("axe DevTools for iOS")
        Spacer()
        Button(action: { openLink() },
               label: {
            Image(systemName: "arrow.up.forward.app")
                .accessibilityHidden(true)
                .frame(minWidth: 50, minHeight: 50)
        })
        .accessibility(removeTraits: .isStaticText)
        .accessibility(removeTraits: .isButton)
        .accessibility(addTraits: .isLink)
    }).padding(16)
        .accessibilityElement(children: .combine)
        // .accessibilityLabel("Axe DevTools for iOS") <-- Add when `Text` is missing to ensure a name is present
}

React Native

To fix an issue found by this rule, add an accessibilityLabel to the interactive element.

<TextInput
  ...
  accessibilityLabel="First Name"
/>

When elements are grouped together within a containing View, add the accessible and the accessibilityLabel properties to it:

<View
   importantForAccessibility='no-hide-descendants'
   accessible={true}
   accessibilityElementsHidden={false}
   accessibilityLabel={"Dark Mode"}
   accessibilityValue={{ text: "" + isEnabled }}
   accessibilityRole='switch'
   onPress={() => { 
      setIsEnabled(!isEnabled) 
    }}
 >            
    <Switch
      trackColor={{ false: 'lightgray', true: 'dimgray' }}
      ios_backgroundColor={'lightgray'}
      thumbColor={'white'}
      onValueChange={ () => {
         setIsEnabled(!isEnabled)
      }}
      value={isEnabled}
      accessibilityElementsHidden={true}
     />
</View>

Flutter

Use the tooltip property on IconButton to provide an accessible name. This sets the name announced by VoiceOver.

  IconButton(
    icon: const Icon(Icons.search),
    tooltip: 'Search',
    onPressed: () {},
  )

When grouping a visible label with an interactive element, wrap them in MergeSemantics so VoiceOver combines them into a single focusable element:

  MergeSemantics(
    child: Row(
      children: [
        const Text("Dark mode"),
        Switch(
          value: _darkMode,
          onChanged: (value) => setState(() => _darkMode = value),
        ),
      ],
    ),
  )

Can I Ignore This Rule?

This rule has a critical impact for users and should not be ignored. An unnamed interactive element is one of the most fundamental accessibility failures. VoiceOver and Voice Control users will struggle to use an element without an accessible name. Take steps to remediate all instances of this issue before addressing lower-priority issues.

Frequently Asked Questions

When using VoiceOver, I hear content read aloud after focusing on the element. Why does this rule still fail? If an element lacks a defined name, the screen reader often will announce its value. However, the value is not a substitute for the missing accessible name. For images in buttons, specifically, VoiceOver may announce the file name of the image. Even if the file name is descriptive, this is not a substitute for the missing accessible name attribute.

Resources

Deque University Course Pages

• See Native Mobile iOS under 4.1.2a Name, Role,Value (A)

  Note: Full access to Deque University resources requires a subscription.

Other Resources

• Web Content Accessibility Guidelines (WCAG) 2.1
  • Understanding SC 4.1.2, Name, Role, Value (Level A)