fix(button): sync aria attributes between host and native button by Zac-Smucker-Bryan · Pull Request #31264 · ionic-team/ionic-framework

Zac-Smucker-Bryan · 2026-07-10T22:08:35Z

Issue number: resolves #30626

What is the current behavior?

The native button inside ion-button is not being updated with the aria-attributes if it changes on ion-button after initial render, including aria-description. Additionally, the same dynamic is happening with other button like elements, including ion-card and ion-item.

What is the new behavior?

The native button inside ion-button updates with the aria attributes if it changes on ion-button. Changes include:

Add 2 helper functions to helpers.ts
- A mutation observer watching for all attribute changes.
- One which watches only for aria attribute changes, which calls the mutation observer.
Add 4 tests to button.e2e.ts in a11y:
- One which loops through each aria attribute (imported from the helper) using ariaAttributes
- One which specifically tests aria-disabled since it is managed in render() separately. Render forced with prop change.
- One which looks at detaching and reattaching behavior
- One which tests the helper strips, sets, accepts empty strings, and can process removeAttribute
Update button.tsx to:
- Add import of new helpers watchForAriaAttributeChanges, type AttributeWatcher from '@utils/helpers'
- Add private ariaWatcher?: AttributeWatcher; to class Button
- Remove previous watch block since now handled by helper
- In connectedCallback()
  - Move this.inheritedAttributes to connectedCallback()
  - Add ariaWatcher and watchForAriaAttributeChanges, replicating functionality of the watch block, but for all aria attributes
  - Add specific exclusion of aria-disabled
In item.tsx,
- Move this.inheritedAttributes to connectedCallback()
- Add ariaWatcher and watchForAriaAttributeChanges, replicating functionality of the watch block, only applying to aria-label currently
In item.e2e.test, add tests to ensure:
- native element updates aria-label when host attribute changes
- aria-label sync survives detach and reattach
- helper strips host attribute and syncs native element through set, empty, and remove
In card.tsx,
- Move this.inheritedAttributes to connectedCallback()
- Add ariaWatcher and watchForAriaAttributeChanges, replicating functionality of the watch block, only applying to aria-label currently
In card.e2e.test, add tests to ensure:
- native element updates aria-label when host attribute changes
- aria-label sync survives detach and reattach
- helper strips host attribute and syncs native element through set, empty, and remove

Does this introduce a breaking change?

Yes
No

@watch

Adds @watch('aria-description') to button.tsx before onAriaChanged

Set aria description and both buttons should match. Update aria description on host button, and both buttons should still match.

vercel · 2026-07-10T22:08:39Z

@Zac-Smucker-Bryan is attempting to deploy a commit to the Ionic Team on Vercel.

A member of the Team first needs to authorize it.

vercel · 2026-07-13T13:27:52Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
ionic-framework	Ready	Preview, Comment	Jul 13, 2026 1:33pm

ShaneK

Thanks for this PR!

I talked to the team about this PR and, while it does look solid and solve the issue's title problem, there's a bit more to it than this.

There's actually 2 remaining issues in the original issue that won't be resolved by this PR:

Many other aria attributes not being copied
Other components that can act like buttons not getting this fix (this was a comment on the issue, but should still be addressed)

The first one I've created an internal follow-up ticket to address because it's much more involved than this solution and something we'll need to review on how to do well. We can't just add 50 @Watchs and call it good.

The second one I'd prefer if we address in this PR

codeCraft-Ritik

Great fix! Synchronizing dynamic aria-description updates with the native button improves accessibility while keeping the component behavior consistent. The accompanying test provides good confidence in the change.

@watch

Previously, ARIA attributes inherited from the host were only captured once at componentWillLoad. Attributes set or changed after initial load (e.g. by ion-input-password-toggle updating aria-label/aria-pressed as visibility toggles) were not reflected onto the native button, causing screen readers to announce stale values unless a watch decorator was used for each attribute. Adds watchAttributes/watchForAriaAttributeChanges to helpers.ts, which use a MutationObserver to keep inherited ARIA attributes in sync for the lifetime of the component. Replaces the previous per-attribute @watch decorators with this more general mechanism. Update Button.tsx to reflect this and use these new helpers. Add tests to test syncing all attributes. Fixes ionic-team#30626

ShaneK

Thanks for reworking this! The helper approach is the right direction and a lot better than adding a @watch per attribute. Left a handful of comments inline.

The two I'd want sorted before this goes in: the watcher gets torn down on disconnectedCallback but never recreated, so aria sync breaks the first time the button moves in the DOM, and covering the other button-like components (ion-item/ion-card at least) from my earlier review. The rest are nits.

…pt to helper Change disconnect to destroy to match other ionic conventions Update onChange to accept null values Add support for removeAttribute, including if null values triggered

…ttributes to connectedCallback Import helper to ion-item and ion-card move inheritedAriaAttributes to connectedCallback in these components to preserve helper call order

Update tests for ion-button with annotations Add tests for removeAttribute and attribute sync to ion-button, ion-card, and ion-item

Zac-Smucker-Bryan · 2026-08-07T18:22:05Z

PR revised based on feedback and expanded scope

ShaneK

Thank you so much for taking a shot at this massive undertaking! Let me know if you'd like me to help you out with this, I know it's a pretty daunting task

ShaneK · 2026-08-07T21:15:28Z

+    // strip would itself be treated as an external removal.
    this.inheritedAriaAttributes = inheritAttributes(this.el, ['aria-label']);
+
+    this.ariaWatcher = watchAttributes(this.el, ['aria-label'], (changed) => {


Worth flagging that the coverage is uneven: button watches everything in ariaAttributes while item and card only watch aria-label, so <ion-item button aria-describedby="hint"> still never reaches the native button. That matches what inheritAttributes already did here so it isn't a regression, but this seems like the natural moment to widen it.

The other button-like components from my earlier comment are still on the load-once path too, ion-back-button and ion-menu-button among them, and I think a handful of others like ion-select and ion-tab-button are as well. Happy for those to go to a follow-up card, I'd just want it written down rather than left implicit.

If you want me to widen it for the item (same thing on card), let me know. I just didn't want to widen things any more than I have.

Likely those other components should be a follow up issue just to try to wrap up these 3 components.

Zac-Smucker-Bryan · 2026-08-07T22:05:56Z

Thank you so much for taking a shot at this massive undertaking! Let me know if you'd like me to help you out with this, I know it's a pretty daunting task

@ShaneK Yes, this PR is pushing the limits of what I know. But I have learned a lot.

I would love your help, especially with the helper.ts to get it to a point where it would... actually be helpful. I suspect you can reduce the complexity better than I can.

I have done an initial review of your comments and think I can address everything else with more helpful tests and such, once we get the right helper structure in place. My only other question would be: in your comment #31264 (comment), you say "Moving the inherit into connectedCallback fixes the watcher lifetime, but I think it trades that for a worse problem." If the ultimate helper means things can go back to the way they were in terms of calls, all the better, I just didn't want to create other issues without thinking it through.

Let me know the best way to collaborate to get it done.

Zac-Smucker-Bryan · 2026-08-17T21:30:10Z

As I am working through things, I think I can have a revised PR/commits/tests etc. next week @ShaneK, and think I even have a helper that is simpler based on your specific feedback.

…on, item, and card

Consistency based on element being tested

Zac-Smucker-Bryan added 2 commits July 10, 2026 16:53

fix(button): sync aria description between host and native button

495ca01

Adds @watch('aria-description') to button.tsx before onAriaChanged

test(button): add e2e test for aria-description sync

a7941a1

Set aria description and both buttons should match. Update aria description on host button, and both buttons should still match.

github-actions Bot added the package: core @ionic/core package label Jul 10, 2026

Zac-Smucker-Bryan marked this pull request as ready for review July 11, 2026 18:09

Zac-Smucker-Bryan requested a review from a team as a code owner July 11, 2026 18:09

Zac-Smucker-Bryan requested a review from thetaPC July 11, 2026 18:09

vercel Bot deployed to Preview July 13, 2026 13:33 View deployment

ShaneK requested changes Jul 13, 2026

View reviewed changes

codeCraft-Ritik reviewed Jul 15, 2026

View reviewed changes

Zac-Smucker-Bryan added 2 commits July 25, 2026 16:12

npm run lint.fix

4ed0c4f

ShaneK requested changes Jul 28, 2026

View reviewed changes

Zac-Smucker-Bryan added 3 commits August 5, 2026 11:35

fix(helper): update Mutation Observer and add removeAttribute interce…

a906acb

…pt to helper Change disconnect to destroy to match other ionic conventions Update onChange to accept null values Add support for removeAttribute, including if null values triggered

fix(button): Add helper to ion-item and ion-card, move inheritedAriaA…

4f78686

…ttributes to connectedCallback Import helper to ion-item and ion-card move inheritedAriaAttributes to connectedCallback in these components to preserve helper call order

test(button): Add e2e tests

b585cd5

Update tests for ion-button with annotations Add tests for removeAttribute and attribute sync to ion-button, ion-card, and ion-item

Zac-Smucker-Bryan changed the title ~~fix(button): sync aria description between host and native button~~ fix(button): sync aria attributes between host and native button Aug 5, 2026

ShaneK requested changes Aug 7, 2026

View reviewed changes

Zac-Smucker-Bryan added 5 commits August 26, 2026 13:47

fix(helper): simplify Mutation Observer for aria attribute watching

ab5fbfd

fix(button): sync aria attributes to native button reactively on butt…

d1c191f

…on, item, and card

test(button): Fix e2e tests for button, item, and card changes

11691fd

fix(test): Update Item and Card native test variable

0aef560

Consistency based on element being tested

fix(item): Merge conflict

6e3e997

github-actions Bot added package: angular @ionic/angular package package: vue @ionic/vue package package: react @ionic/react package labels Aug 26, 2026

Uh oh!

Conversation

Zac-Smucker-Bryan commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What is the current behavior?

What is the new behavior?

Does this introduce a breaking change?

Uh oh!

vercel Bot commented Jul 10, 2026

Uh oh!

vercel Bot commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ShaneK left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codeCraft-Ritik left a comment

Choose a reason for hiding this comment

Uh oh!

ShaneK left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Zac-Smucker-Bryan commented Aug 7, 2026

Uh oh!

ShaneK left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ShaneK Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

Zac-Smucker-Bryan Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

Zac-Smucker-Bryan commented Aug 7, 2026

Uh oh!

Zac-Smucker-Bryan commented Aug 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Zac-Smucker-Bryan commented Jul 10, 2026 •

edited

Loading

vercel Bot commented Jul 13, 2026 •

edited

Loading

ShaneK left a comment •

edited

Loading