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
- Add private didLoad = false; for conditional use in connectedCallbackand use in added componentDidLoad for starting the watcher after initial component load
- Remove previous watch block since now handled by helper
In item.tsx,
- Add ariaWatcher and watchForAriaAttributeChanges, replicating functionality of the watch block, only applying to aria-label currently
- Use existingprivate didLoad = false; for conditional use in connectedCallbackand use in existing componentDidLoad for starting the watcher after initial component load
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,
- Add ariaWatcher and watchForAriaAttributeChanges, replicating functionality of the watch block, only applying to aria-label currently
- Add private didLoad = false; for conditional use in connectedCallbackand use in added componentDidLoad for starting the watcher after initial component load
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

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
ionic-framework	Ready	Preview	Sep 15, 2026 4:54pm UTC

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.

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.

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

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.

@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.

@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

…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

…on, item, and card

Consistency based on element being tested

@utils/helpers was imported twice and passed npm run lint but failed build. Now, it is imported only once.

ShaneK

This is really close now, and the helper itself is in good shape after the last round.

The one I'd want sorted is the ignore list on ion-card and ion-item. They inherit only aria-label but watch all ~49 ARIA attributes, so role and aria-hidden reach the native element after load when neither does at load. On ion-item that means the inner <button> can end up carrying role="listitem". Swapping those two calls to watchAttributes(this.el, ['aria-label'], ...) covers it.

The other is the detach/reattach and aria-disabled tests. I reverted the four source files to main, kept the specs, and both still pass, so neither covers the thing it's named for.

Everything else is nits. If you'd rather hand this off at this point just say the word and I can finish it up. Thank you for sticking with this one, it's a much better fix than where it started.

I've taken on maintenance of this PR

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

ShaneK requested changes Jul 28, 2026

View reviewed changes

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

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

Zac-Smucker-Bryan added 11 commits August 26, 2026 21:31

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

456c161

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

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

d2b73ee

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

npm run lint.fix

7210eff

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

c014ca5

…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…

dab84cb

…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

610c1a6

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

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

1c94795

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

31ae424

…on, item, and card

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

962baac

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

f142f36

Consistency based on element being tested

Zac-Smucker-Bryan force-pushed the button-aria-description branch from 6e3e997 to f142f36 Compare August 27, 2026 02:43

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

Zac-Smucker-Bryan requested a review from ShaneK August 27, 2026 14:06

vercel Bot deployed to Preview August 31, 2026 18:30 View deployment

fix lint build error - duplicate imports

8bea648

@utils/helpers was imported twice and passed npm run lint but failed build. Now, it is imported only once.

vercel Bot deployed to Preview August 31, 2026 21:05 View deployment

ShaneK previously requested changes Sep 1, 2026

View reviewed changes

ShaneK added 2 commits September 14, 2026 11:24

Merge branch 'main' into button-aria-description

868ba5b

fix(button, card, item): keep aria attributes in sync with the host

1ab1c95

vercel Bot deployed to Preview September 15, 2026 16:54 View deployment

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!

Uh oh!

Zac-Smucker-Bryan commented Aug 7, 2026

Uh oh!

Zac-Smucker-Bryan commented Aug 17, 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!

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