Label in Name

Learn how we're using artificial intelligence for this rule!

What We Check For

If an interactive element has a visible label, the name announced by assistive technology (AT) should be the same.

Element	Failing ❌	Passing ✅
Button with text	name = "Log in"	name = "Sign in"
Match	Name does not match visible label	Name matches visible label
VoiceOver	"Log in, button"	"Sign in, button"
Voice Access	User speaks out loud "Sign in" This will not activate the button because the name is "Log in", not "Sign in"	User speaks out loud "Sign in" This should activate the button because the name is "Sign in"

At a Glance

• This rule has a serious impact for users
• Match the visible text: If sighted users can see a "Sign in" button, make sure screen readers also announce "Sign in"
• It's okay to add extra context: "Save" can become "Save document"
• Never leave out visible words: Screen readers should announce a "Search catalog" button, not just "Search"

Impact to Users

People using assistive technology such as VoiceOver and/or experiencing low vision are impacted most by issues detected. Label in Name issues can contribute to a confusing or conflicting experience between the announcement from VoiceOver and the content on the screen.

Refer to the table above. If a button has visible text on it saying "Sign in", VoiceOver should also announce "Sign in" - not something different, such as "Login".

Note: Depending on the programming language, the 'name' property for an element may be called something different. In Swift and React Native, for example, it is called an accessibility label.

Confirm Label in Name Issue

1. Turn on VoiceOver
2. Attempt to focus on the element
3. One of the following will happen:

• Inaccessible: Text announced by VoiceOver is different from the element's visible text
  • Accessible: Text announced by VoiceOver is the same or includes the element's visible text
• Accessible: VoiceOver will announce the element's visible text.

Fix Issues

To resolve Label in Name issues, set a name for the element that either matches or contains the element's visible text.

When the visible text is descriptive and unique, then it is recommended to have the name match the text exactly.

When the visible text by itself doesn't explicitly tell AT users (e.g. screen reader) the action of the element, then it would be a good idea to expand the accessible name to include more context. For example:

• Visible Label: “Inbox, 5”, Name: “Inbox, 5 unread messages”
• Visible Label: “Delete”, Name: “Delete User Profile”

UIKit

In storyboard:

1. Select the element with a LabelInName issue
2. Ensure that the Inspector Panel is visible
3. Select the Identity Inspector
4. Under Accessibility, there is a category called "Label". Enter a label that exactly matches or includes all of the visible text.

In code:

Find where the accessibility label was set and ensure that the accessibility label's value either matches or contains all the visible text of the element.

button.title = "Search"
button.accessibilityLabel = "Search the store"
// Not an exact match, but the accessibilityLabel includes all the visible text

SwiftUI

Set an accessibility label that either matches or contains the visible text.

Button(action: {
    openMenu()
}) {
    Text("Sign in")
}.accessibility(label: Text("Sign in"))
// The visible text and accessibility label match exactly

React Native

The accessibilityLabel property should either match or contain the visible text.

By default, a button will use its title as its accessibilityLabel, and will therefore pass this rule.

<Button 
   title={'Menu'}
   mode='contained'
   accessibilityLabel='Menu'
/>

For interactive elements without a title, use a touchable view that contains the control and text components. In this manner, the text element becomes the visible label for the control. Set the containing element's accessibilityLabel to either match or contain the visible text.

<TouchableOpacity
   style={styles.switchRow}
   importantForAccessibility='no-hide-descendants'
   accessible={true}
   accessibilityElementsHidden={false}
   accessibilityLabel='Subscribe to notifications'
   accessibilityValue={{ text: "" + isEnabled }}
   accessibilityRole='switch'
   onPress={() => { 
     setIsEnabled(!isEnabled)
   }}> 
     <Text style={{ fontSize: 22 }}> 
        Subscribe
     </Text>
     <Switch
        trackColor={{ false: 'lightgray', true: 'dimgray' }}
        ios_backgroundColor={'lightgray'}
        thumbColor={'white'}
        accessibilityElementsHidden={true}
        importantForAccessibility='no-hide-descendants'
        value={isEnabled}

         onValueChange={() => {
           setIsEnabled(!isEnabled);
         }}
     />
</TouchableOpacity>

Can I Ignore This Rule?

Label In Name has a Serious impact for users, and we recommend taking steps to remediate this issue except in rare cases. For example, if you have a button with visible text that says "Visa Card xxxx-xxxx-xxxx-1234" you may want to set the text announced by VoiceOver to say "Visa Card ending in 1-2-3-4". Since the text on the button does not match the name announced by VoiceOver, this would cause a failure for Label in Name. But in a case such as this, it would make sense to ignore the rule. Learn more about ignoring rules.

Resources

Deque University Course Pages

• 2.5.3 Label in Name (A)
• Success Criterion 2.5.3 - Label in Name
• Requirements - 2.5.3.a Label in Name

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

Other Resources

• Web Content Accessibility Guidelines (WCAG) 2.1, W3C Recommendation
  • Success Criterion 2.5.3 - Label in Name
• WCAG 2.1 Understanding Docs
  • Understanding 2.5.3 A - Label in Name