fix(button): sync aria description 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.

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.
- Added Export to ariaAttributes so it could be imported for use in tests
Add 2 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
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 componentWillLoad()
- Add ariaWatcher and watchForAriaAttributeChanges, replicating functionality of the watch block, but for all aria attributes
- Add specific exclusion of aria-disabled

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.

ShaneK · 2026-07-28T19:08:18Z

+     * aria-disabled is excluded here (and from the initial inheritAriaAttributes
+     * call above) because button.tsx sets it itself on Host based on the `disabled` prop
+     */
+    this.ariaWatcher = watchForAriaAttributeChanges(


Good call making this a reusable helper. Makes sense to keep the first pass to ion-button and get reactions before going wider. On the scope question: the main thing from my earlier review is covering the other button-like components too. The same one-time-copy bug is in ion-back-button, ion-menu-button, ion-fab-button, and ion-breadcrumb, plus ion-item and ion-card which @ReneZeidler called out on the issue. Could we pull at least ion-item and ion-card into this PR? One thing to watch out for: item/card only inherit aria-label today, so we can't copy the button wiring as-is, we'd want to pick the attribute set / ignoreList per component so we don't suddenly start stripping all ~50 aria attributes off the host.

ShaneK · 2026-07-28T19:08:35Z

+  }
+
+  // Prevents
+  disconnectedCallback() {


I think this breaks after the button moves in the DOM. The watcher gets created in componentWillLoad, which only runs once, but it's disconnected and cleared here on every disconnectedCallback. There's no connectedCallback to recreate it, so the first time an ion-button is detached and reattached (keyed list reorder, ion-nav, virtual scroll) the observer is gone for good and aria reactivity silently stops. The old @Watch decorators survived reconnection on their own. Every other MutationObserver in core is created in connectedCallback and torn down in disconnectedCallback (input.tsx, select.tsx, checkbox.tsx), so moving creation there would match those and fix the reconnect case. Worth an e2e test that detaches and reattaches, then checks a later aria change still lands.

Also the // Prevents comment just above looks cut off, might want to finish it or drop it.

ShaneK · 2026-07-28T19:08:36Z

+      const name = mutation.attributeName;
+      if (!attributes.includes(name)) continue;
+      const value = el.getAttribute(name);
+      if (value === null) continue;


One gap here: because we skip on value === null and strip the attribute off the host after the first copy, there's no way to reactively remove an aria attribute from the native button once it's been set. A later removeAttribute on the host fires no mutation since it's already gone, so the native element keeps the stale value. Toggling between two non-null values is fine, it's only clearing that's affected. Might be worth recording removals in changed so the native element can drop them too, with a test to cover it. I'm not sure how often clearing an aria attr comes up in practice, so I'll leave the priority up to you.

ShaneK · 2026-07-28T19:08:37Z

+    const watchedAriaAttributes = ariaAttributes.filter((attr) => attr !== 'aria-disabled');
+
+    for (const attr of watchedAriaAttributes) {
+      test(`native button updates ${attr} when host attribute changes`, async ({ page }) => {


These verify the fix for the linked issue, so could you add the issue annotation to keep the context linkable?

test(`native button updates ${attr} when host attribute changes`, async ({ page }, testInfo) => { testInfo.annotations.push({ type: 'issue', description: 'https://github.com/ionic-team/ionic-framework/issues/30626' });

Same for the aria-disabled exclusion test.

ShaneK · 2026-07-28T19:08:38Z

+
+    /**
+     * Keeps inherited ARIA attributes in sync with the host element for the
+     * lifetime of the component, not just at initial load. This replaces the


Small nit: the "This replaces the previous approach of manually re-declaring @watch..." line is more PR context than something the code needs to carry, since a future reader won't have the old code to compare against. I'd keep the aria-disabled note right below it though. Up to you!

ShaneK · 2026-07-28T19:08:39Z

 };

+export interface AttributeWatcher {
+  disconnect: () => void;


Nit: our other wrapper-object controllers use destroy() (SlotMutationController, NotchController), and disconnect() is what we tend to call on a raw MutationObserver. Since this returns a wrapper, destroy would match what we do elsewhere. No worries if you'd rather leave it.

ShaneK · 2026-07-28T19:08:40Z

+
+configs({ directions: ['ltr'] }).forEach(({ title, config }) => {
+  test.describe(title('button: aria attribute sync'), () => {
+    // Mirrors the ignoreList passed to inheritAriaAttributes/watchForAriaAttributeChanges


Nit: comments in tests hold up better describing the behavior instead of pointing at the source file, since the file reference goes stale if things move. The reason is worth keeping though, something like: aria-disabled is excluded because the button owns it via the disabled prop, so it shouldn't be host-synced. Up to you!

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

fix(button): sync aria description between host and native button#31264
Zac-Smucker-Bryan wants to merge 4 commits into
ionic-team:mainfrom
Zac-Smucker-Bryan:button-aria-description

Zac-Smucker-Bryan commented Jul 10, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jul 10, 2026

Uh oh!

vercel Bot commented Jul 13, 2026 •

edited

Loading

Uh oh!

ShaneK left a comment •

edited

Loading

Uh oh!

codeCraft-Ritik left a comment

Uh oh!

ShaneK left a comment

Uh oh!

ShaneK Jul 28, 2026

Uh oh!

ShaneK Jul 28, 2026

Uh oh!

ShaneK Jul 28, 2026

Uh oh!

ShaneK Jul 28, 2026

Uh oh!

ShaneK Jul 28, 2026

Uh oh!

ShaneK Jul 28, 2026

Uh oh!

ShaneK Jul 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

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!

ShaneK Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

ShaneK Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

ShaneK Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

ShaneK Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

ShaneK Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

ShaneK Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

ShaneK Jul 28, 2026

Choose a reason for hiding this comment

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