Custom Labels

• Authors: Kefas Lungu

Note: this add-on requires NVDA 2025.1 or later.

Overview

Custom Labels is an NVDA add-on that allows you to add custom labels for unlabeled controls and edit existing ones. This is particularly useful for applications with buttons or controls that doesn't have labels or NVDA cannot properly identify.

Features

• Assign custom labels to unlabeled controls
• Edit existing custom labels
• Remove custom labels when no longer needed
• Manage all labels through a settings panel
• Labels are stored per-application for better organization, and for exporting and importing for sharing later

Supported Control Types

The following control types can be labeled:

• Buttons
• Menu buttons
• Toggle buttons
• Checkboxes
• Radio buttons
• Combo boxes
• Sliders
• Tabs
• Menu items
• Editable text

Gestures

• NVDA+Control+L: Set or edit a custom label for the current control
• NVDA+Control+Delete: Remove the custom label from the current control
• NVDA+Control+J: Check if the current control has a custom label
• NVDA+Control+; (semicolon): Open custom labels settings

Usage

Setting a Custom Label

1. Focus on a control you want to label
2. Press NVDA+Control+L
3. A dialog will appear showing information about the control
4. Enter the desired label in the text field
5. Press OK to save the label

Editing an Existing Label

1. Focus on a control that has a custom label
2. Press NVDA+Control+L
3. Modify the label in the text field
4. Press OK to save the changes

Removing a Label

You can remove a label in two ways:

1. Focus on the control and press NVDA+Control+Delete
2. Or open the label dialog (NVDA+Control+L) and press the Remove button

Managing All Labels

1. Press NVDA+Control+; to open the Custom Labels settings panel
2. Browse labels organized by application
3. Use the Edit, Remove, Remove App, or Remove All buttons as needed

Settings Panel

The Custom Labels settings panel can be accessed through:

• The keyboard shortcut NVDA+Control+;
• NVDA menu > Preferences > Settings > Custom Labels

The panel displays all custom labels organized in a tree view by application. You can:

• Edit: Modify the selected label
• Remove: Delete the selected label
• Remove App: Delete all labels for the selected application
• Remove All: Delete all custom labels

Storage

Labels are stored in JSON files in NVDA's configuration directory under a customLabels folder. Each application has its own JSON file, making it easy to backup or share labels for specific applications.

Known Limitations

• Web-based applications in browse mode: For applications built with web technologies (such as Outlook new, Slack, TeamViewer, and other Electron/WebView2 apps), custom labels only work in focus mode. Press NVDA+Space to switch to focus mode before using custom labels in these applications. This is due to how NVDA handles browse mode using a virtual buffer, which does not use the same live objects that custom labels rely on.
• Controls with identical properties: If an application has multiple controls of the same type with the same name (or no name), some times custom labels cannot distinguish between them. Labeling one will label all matching controls. This is rare in practice, as most applications assign unique identifiers to their controls.

Contributors

• Leonardo Marenda (@LeonardoMarenda): Added Italian translation. (#1)
• Kostenkov-2021 (@Kostenkov-2021): Added Russian README and localization. (#3)
• Umut KORKMAZ (umutkork@gmail.com): Added Turkish translation.
• George-br (@George-br): Added Ukrainian translation. (#6)

Changelog

Version 2026.1

• Added Ukrainian, Russian and Turkish translations.
• Improved control identification using original control name.
• Fixed labels not working in web-based applications (Electron, WebView2).
• Fixed all buttons getting the same label in some applications.
• Added support for labeling Editable text.
• Added known limitations documentation.

Version 2026.0

• Initial release