Skip to main content
Accessibility Field Guide

Accessible Names

A practical Field Guide page about how controls get the names people hear, see, speak, and navigate by.

A person carries two cardboard boxes with visible labels on the front.
Photo: A Person Carrying Cardboard Boxes with Labels via Pexels — https://www.pexels.com/photo/a-person-carrying-cardboard-boxes-with-labels-9603487/
View full screen Download image

An accessible name is the name a control exposes to assistive technology.

It is how a button, link, form field, image link, or custom control answers a simple question:

What is this thing called?

That name matters because users do not always interact with a screen by looking at the full visual layout.

Some people navigate by a screen reader list of links or buttons. Some tab through controls one at a time. Some use voice control and speak the visible name of a button. Some zoom in and only see part of the screen at once.

If the control has a clear accessible name, people have a better chance of understanding what it is and what it does.

If the name is missing, vague, repeated, or different from the visible label, the interface becomes harder to use than it needs to be.

The common project moment

A screen looks understandable in a design file.

There is a search icon. A row of cards. A few Read more links. A table with Edit buttons. A trash-can icon. A form field with placeholder text. A custom dropdown. A close button in a modal.

Visually, the surrounding layout seems to explain everything.

But the programmatic names may tell a different story:

  • a search button named only Button
  • several links named Read more
  • an icon button with no name at all
  • a form field announced as Edit text blank
  • a visible Save button with an accessible name of Submit form
  • a close button named X
  • a custom control with a role but no useful name

That gap is where accessibility problems often show up.

The screen may look clear, but the names exposed to users may be incomplete or confusing.

What an accessible name does

An accessible name gives a control its usable identity.

For example:

  • A button might be named Save changes.
  • A link might be named Review readiness checklist.
  • A form field might be named Email address.
  • An icon-only button might be named Search records.
  • A close button might be named Close dialog.

The name does not have to explain everything.

It should give enough information for the user to recognize the control, understand its purpose, and operate it with confidence.

Start with visible text when you can

The safest accessible name is usually the visible label people can already see.

A real button with text gets its name from that text:

<button>Save changes</button>

A real link with clear link text gets its name from that text:

<a href="/accessibility-field-guide/review-readiness/">Review readiness</a>

A labeled form field gets its name from the label:

<label for="email">Email address</label>
<input id="email" name="email" type="email">

This is one reason native HTML is such a strong starting point. When the visible text, native element, and programmatic name all line up, there is less for the team to rebuild manually.

Keep the visible label and accessible name aligned

The accessible name should usually include the visible label.

This is especially important for voice control.

If a visible button says Save, a user may say “click Save.” If the accessible name is only Submit form, the voice-control command may not match what the user sees.

Better patterns include:

  • Visible label: Save; accessible name: Save changes
  • Visible label: Search; accessible name: Search records
  • Visible label: Delete; accessible name: Delete uploaded document

Best of all, when space allows, make the visible label complete:

  • Save changes
  • Search records
  • Delete uploaded document

That way the visual interface and the programmatic interface tell the same story.

Do not replace useful visible text with worse hidden text

ARIA can name controls, but it can also create confusion when used carelessly.

For example:

<button aria-label="Submit form">Save</button>

The visible label says Save, but the accessible name is Submit form.

That mismatch can make the control harder to operate with voice control and harder to review because the visible interface and assistive-technology interface no longer match.

A better version would be:

<button aria-label="Save changes">Save</button>

Or, more simply:

<button>Save changes</button>

Use ARIA labels when they clarify something the visible text cannot provide by itself. Do not use them to hide vague labels from the visual design.

Name icon-only controls clearly

Icon-only buttons need names.

An icon might be visually familiar, but it may not expose a useful name on its own. A button that contains only an SVG or icon font can end up unnamed unless the team provides a name.

For example:

<button aria-label="Search records">
  <svg aria-hidden="true" focusable="false">...</svg>
</button>

The icon is hidden from assistive technology, and the button has a clear name.

Common icon-only controls include:

  • search
  • menu
  • close
  • edit
  • delete
  • download
  • expand or collapse
  • previous or next

Be specific when the consequence matters.

Delete uploaded document is clearer than Delete. Close dialog is clearer than Close when there may be several close-like controls on a page.

Make repeated names unique enough

Repeated controls often need more than a short label.

A table may have ten Edit buttons. A document list may have several Download links. A card grid may repeat Read more over and over.

If the accessible names are identical, users may not know which item each control affects.

Better names include:

  • Edit mailing address
  • Download January statement
  • Read more about keyboard-only navigation
  • Remove proof of income attachment
  • View vendor accessibility questions

The point is not to make every name long.

The point is to include the missing object or destination when the short label is not enough.

Form fields need real names

Form fields should not depend on placeholder text alone.

A placeholder may disappear when someone types. It may be lower contrast. It may not be announced consistently as the field's name. It also leaves reviewers guessing whether the field has a real programmatic label.

Prefer a visible label connected to the field:

<label for="case-number">Case number</label>
<input id="case-number" name="case-number">

For grouped fields, the group also needs a name.

<fieldset>
  <legend>Preferred contact method</legend>
  <label><input type="radio" name="contact" value="email"> Email</label>
  <label><input type="radio" name="contact" value="phone"> Phone</label>
</fieldset>

The individual options have names, and the group has a question.

Without the group name, the user may hear the options but not know what question they answer.

Images that act like controls need names too

If an image is also a link or button, the image's text alternative may become the name of the control.

That means the alt text needs to describe the link or action, not just the visual decoration.

For example, if a logo image links to the home page, the useful name may be:

<a href="/">
  <img src="logo.svg" alt="Tommy's Field Notes home">
</a>

If the image is decorative inside a link that already has text, the image may need empty alt text so it does not add noise.

The question is practical:

What should the user hear or speak when they reach this link or button?

Custom components need extra naming decisions

Native controls often get names from their text, labels, or associated elements.

Custom controls do not always get that for free.

If a team builds a custom component, they need to decide:

  • What role does the component expose?
  • What is its accessible name?
  • Does the name include the visible label?
  • Does the name change when the visible label changes?
  • Does the name stay clear when repeated in a list?
  • Are state and value exposed separately from the name?

A custom dropdown, combobox, tab, accordion, switch, or dialog trigger may look right visually but still be hard to use if its name is missing or unclear.

Do not put everything in the name

An accessible name should identify the control.

It should not become a long instruction manual.

Other information can be provided through surrounding text, instructions, descriptions, validation messages, or help text.

For example, a field name might be Email address.

The instruction might be We will use this email to send status updates.

Those are related, but they are not the same thing.

If everything is packed into the name, the control can become noisy and repetitive. If too little is in the name, the control can become mysterious.

Aim for a clear name plus useful supporting context.

Questions teams can ask

During design and content

  • Does each control have visible text when visible text would help?
  • Are icon-only controls truly necessary?
  • Would the visible label still make sense if someone used voice control?
  • Are repeated labels specific enough to distinguish one item from another?
  • Are destructive or final actions named with the object they affect?
  • Does the label tell the same story as the expected behavior?

During development

  • Does each interactive element have an accessible name?
  • Is the accessible name coming from native text or a connected label when possible?
  • If aria-label or aria-labelledby is used, does it clarify rather than override useful visible text?
  • Does the accessible name include the visible label?
  • Are decorative icons hidden from assistive technology when the control already has text?
  • Are custom controls exposing a role, name, state, and value that match their behavior?

During QA

  • Can you understand the controls by tabbing through them one at a time?
  • Does a screen reader announce useful names for buttons, links, and fields?
  • Does a links list or buttons list contain repeated vague names?
  • Can voice-control users activate a control by saying the visible label?
  • Are form fields announced with the same labels users can see?
  • Do icon-only buttons announce clear actions?

Common trail hazards

  • Icon-only buttons with no accessible name.
  • Visible labels that do not match accessible names.
  • aria-label used to replace, rather than support, visible text.
  • Several controls with the same name, such as Edit, View, Delete, or Read more.
  • Placeholder text used as the only form-field label.
  • Form groups without a group name or question.
  • Images inside links with missing, vague, or noisy alt text.
  • Custom components with roles and states but no clear name.
  • Long accessible names that include too much instructional text.
  • Names that describe the visual icon instead of the action, such as magnifying glass instead of Search records.

Small habit

For each interactive control, ask:

What would someone hear if they landed here without the full visual context?

Then compare that to what someone sees.

If the visible label says one thing and the accessible name says another, fix the mismatch.

If the control has no useful name, give it one.

If five controls have the same name, add the missing object or destination.

A clear name is not extra polish. It is part of how the interface works.

Use these as trail markers, not as the whole conversation:

  • Native HTML First — for choosing elements that already expose useful names, roles, and behavior.
  • Button vs Link — for matching the control role to the result people expect.
  • Name, Role, and Value — for checking role, state, value, and keyboard behavior when a control is custom.
  • ARIA Is Not Duct Tape — for checking whether hidden ARIA names or attributes are supporting real behavior or masking a deeper issue.
  • Accordions — for checking expandable sections, button headers, keyboard behavior, and expanded or collapsed state.
  • Combobox — for checking names on autocomplete inputs, clear buttons, popup controls, and selected values.
  • Link Text and Button Labels — for visible wording that makes actions and destinations clear.
  • Alt Text Basics — for image links, image buttons, and icon-only controls that need useful alternatives.
  • Headings and Page Structure — for page sections and labels that provide context around controls.
  • Tables and Data Displays — for repeated row actions, sortable headers, icon buttons, and controls inside data displays.
  • Accessibility Glossary — for plain-language definitions of common accessibility terms used across this guide.

What to do next