✅ Accessible Icons and Hidden Labels

[jsulpis]

Summary

This RFC proposes a new approach to handling icon accessibility across the codebase. The core change is to make all icons aria-hidden by default and introduce a VisuallyHidden component or use a Tooltip to set an accessible name for cases where icons carry semantic meaning in interactive elements.

Motivation

Currently, icons throughout our interfaces are exposed to assistive technologies even when they are decorative. This pollutes the accessibility tree and creates a noisy experience for screen reader users.

When icons are informative (e.g., inside buttons), the current approach of deriving labels from icon names is problematic:

• Icon names don't always map to their semantic meaning (e.g., ArrowRight → "Next")
• Labels set via aria-label are not ideal because they often gets overlooked in automatic browser translation and screen reader support is not as good as visually hidden content.

Proposal

1. All Icons Are aria-hidden

Icons should be decorative by default and always include aria-hidden="true".

2. Introduce VisuallyHidden Component

Create a reusable <VisuallyHidden> component for semantically meaningful content that should remain invisible to sighted users but available to assistive technologies.

3. Label Handling

How to set an accessible name when icons carry meaning.

3.1 Accessible label in a tooltip

A tooltip can carry the label of an icon button using an aria-labelledby attribute on the button that targets the tooltip containing the label.

3.2 Visually hidden label without tooltip

If we want to set an accessible label without having a tooltip, we can use the VisuallyHidden component to carry the label. This should be relatively rare (prefer a tooltip in most case to clarify the label for sighted users).

3.3 Description in a tooltip

The tooltip can display an auxiliary description which brings additional details to the label: e.g. a button with label "Notifications" and description "View and manage notifications settings".

In that case the button still needs an accessible label. This label can either be a visible content, or hidden using VisuallyHidden in an icon button for instance. The tooltip is linked to the button with an aria-describedby attribute.

Open Questions

Q1: How to create the tooltip(s) for accessible name and description

When an icon is used without visible text (e.g., icon-only button), how do we set the tooltip with the label ?

Proposed approaches:

1. Using the tooltip component

Use the existing Tooltip component with the icon button

// Before
<Button aria-label="Next">
  <Icon name="ArrowRight" />
</Button>

// After
<Tooltip text="Next">
  <Button>
    <Icon name="ArrowRight" />
  </Button> 
</Tooltip>

• pros:
  • no added complexity to the components
  • explicit behavior
  • can be used directly in all components where it's needed
• cons:
  • a bit verbose if icon buttons are widely used (not sure if it's the case ?)
  • not trivial to migrate from aria-label in existing codebases
  • some components could need a hidden label but without a tooltip, AND not have children where to add VisuallyHidden, like the TextInput. In that case a property might be needed anyway, which is the other option below.

The same approach could be used to set a description in the Tooltip: add a visible content in the Button as the label, and use a Tooltip component with aria-describedby for the description.

2. Using a dedicated property accessibleName

Add a property in the Button that renders the label in a Tooltip

// Before
<Button aria-label="Next">
  <Icon name="ArrowRight" />
</Button>

// After
<Button accessibleName="Next"> // <- renders "Next" in a tooltip paired with `aria-labelledby` attribute
  <Icon name="ArrowRight" />
</Button>

• pros:
  • cleaner API
  • easy to migrate from aria-label
  • in the future this could allow to implement the setting that @iManu suggested, to choose between icon only / icon + label / only label. The button could indeed override its children with the accessibleName (only text) or render it next to the children (icon + text)
  • the same property could be used in components like the TextInput to have a hidden label (which doesn't have to be in a Tooltip, could be VisuallyHidden)
• cons:
  • added complexity in the Button and a new property
  • for consistency the property should be added in all components that could need a label in a tooltip
  • it's not explicit that the accessibleName will render a tooltip (but maybe it's not a bad thing)
  • possible weight added if the Button imports the Tooltip component (although it could be lazy-loaded)

The same approach could be used to set a description using an accessibleDescription property, which will render the description in a Tooltip with aria-describedby. If an accessibleName AND accessibleDescription are provided, the label can be rendered in VisuallyHidden and the description in tooltip.

Important note: the Button component already has a tooltip property but we can't choose if it's a label or a description. We could deprecate it in favor of accessibleName / accessibleDescription.

Q2: Can we generalize a pattern in other components ?

In order to be consistent, we should also migrate other components currently using aria-label. The previous question still applies: how do we set the label(s) ?

1. Keep existing label props and hide them

Add a property to visually hide <label> elements instead of using aria-label

// Before:
<TextInput aria-label="Label" />

// After: additional prop to hide the label
<TextInput label="Label" hideLabel />

• pros:
  • seems more straightforward for components that already have a label prop like form elements
• cons:
  • seems bad to add two props (label + hideLabel) on components that don't have a label prop
  • yet another way to set labels, different from the two proposals in the previous question

2. Reuse the same accessibleName property as proposed before

Each component can decide if the accessibleName is rendered in a tooltip (like the Button) or in the VisuallyHidden component (like the TextInput)

// Before:
<TextInput aria-label="Label" />

// After: wrap the `<label>` element in `<VisuallyHidden/>` (or better: render the `VisuallyHidden` component as a `label` tag to avoid an extra HTML element)
<TextInput accessibleName="Label" />

• pros: consistent with the proposal for buttons
• cons: ?

Implementation Considerations

1. Migration path: How do we handle existing components? Probably deprecate the aria-label props. If we choose to use the accessibleName property, we could use the aria-label if it's present, and the tooltip prop of the Button, which would provide an automatic migration for existing codebases.
2. Documentation: Update component docs with accessibility guidelines
3. Linting rules: Consider creating lint rules to enforce proper usage of labels and icons

Decision

After discussions and vote, here are the final decisions:

• add two new properties tooltipLabel and tooltipDescription on the Button component and all other components that can have a tooltip label or description.
• add a property accessibleLabel on components that can have a hidden label without a tooltip, like SearchInput
• add a global sr-only CSS class that can be added to hide a content while keeping it accessible to assistive technologies
• add a VisuallyHidden component which renders a content with the sr-only class. Use an as prop to personalize the tag and forward all properties

Next Steps

• Gather feedback on this RFC
• Decide on using a property (with what name) vs children
• Implement VisuallyHidden component
• Create migration guide for existing components
• Update documentation

---

Changelog

• 2026-07-16: rework the RFC to handle tooltips in addition to hidden labels
• 2026-07-23: add final decision

Comments and feedback welcome. Please respond in the associated discussion thread.

[jsulpis]

IMHO: create an accessibleName property on components that have a single label, and labels (object) property for components with multiple labels (like it has been done for the recent Filters component).

Reason: using VisuallyHidden in the children works for components that have children (like the Button), but doesn't work in components without children (like TextInput) so that would require at least two different methods. Outdated with the new version of the RFC. The VisuallyHidden component can be used in an icon button to have a hidden label (possibly in addition to the accessibleDescription prop to have a description in a tooltip)

[iManu]

My 2 cents:

• use label and labels for the props names
• TextInput
  • on this: "Add a property to visually hide elements instead of using aria-label": imho an input label tag should never be hidden
  • Improve doc to be explicit on placeholder & label usages
  • There is a labelDescription prop, what about update it to description to avoid confusion

[jsulpis]

• Do you mean label instead of accessibleName ? In that case I think label doesn't convey the idea that it can be hidden, and it's already used in many form components so it would be difficult to generalize
• I think it can happen in some cases like a search bar where a visible label would not be needed
• I find description more confusing than labelDescription because it's not the description of the component, it's juste a content positioned next to the label

[iManu]

• good point, maybe accessibleLabel or relevantLabel sounds better because at the end the tag is a label this is more explicit
• ok, if it is visually-hidden it is good for me then
• did not find labelDescription anymore, seems accessibleDescription replace it, btw ok with that

[iManu]

Feature suggest: Maybe it is too early, but can you consider improvement that made possible for user to choose display options, like what some softwares do:

• Icon only
• Icon + text
• Text only

[jsulpis]

that's interesting, although maybe not in the near future as you said. I included it in the new version of the RFC

[iManu]

About VisuallyHidden

• it should use span tag as default
• sometimes using as props can benefit to add semantic for screen reader: i.e. as="small | strong | caption | …"

[jsulpis]

I don't understand the as prop you are referring to, is it a React prop or native HTML attribute ?

[iManu]

A React prop. We used it on old VisuallyHidden component for website, with the benefits to change the tag depending on context/semantic

NOTE:

• We have removed the VisuallyHidden, after voting in the team about DX improvments, we now use tag directly with a global css class .sr-only