Skip to content

feat(banner)!: make hidden content inert and fix live region semantics - #5056

Open
lukemorawski wants to merge 19 commits into
callstack:mainfrom
lukemorawski:feat/banner-a11y-inert-when-hidden
Open

lukemorawski wants to merge 19 commits into
callstack:mainfrom
lukemorawski:feat/banner-a11y-inert-when-hidden

Conversation

@lukemorawski

@lukemorawski lukemorawski commented Aug 18, 2026 •

Copy link
Copy Markdown
Contributor

Motivation

A hidden Banner stayed mounted, so screen readers and Tab still reached it, and its live region did nothing on iOS and Android.

  • Hidden content is inert while hiding, then unmounts.
  • Live region on all platforms: status by default, urgent for alert. Announced only on hidden to visible.
  • If a focused action goes away, focus moves to the next action or the message.
  • At most 2 actions, inline from 600dp.

Breaking: see the migration guide. Device results, gaps: first comment.

Related issue

Fixes #5055, part of #4990

Screenshots / Videos

web-after-focus-rescue-remove-B.webm

Test plan

Banner example, screen reader on:

  1. Show it: the message is read once.
  2. Hide it: nothing in it is reachable, Tab skips it.
  3. Web: Tab to an action, press it so it goes away: focus moves to the next action or the message.

@MikitasK MikitasK left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

looks pretty solid 👍
just a few points to address before merge:

Comment thread src/components/Banner.tsx Resolved
Comment thread src/components/Banner.tsx Resolved
Comment thread src/components/Banner.tsx Resolved
Comment thread src/components/Banner.tsx Resolved
Comment thread src/components/Banner.tsx Resolved
Comment thread src/components/Banner.tsx Resolved
Comment thread src/components/Banner.tsx Resolved
Comment thread src/components/Banner.tsx
Comment on lines +423 to +429
<View
testID={`${testID ?? 'banner'}-icon`}
style={styles.icon}
aria-hidden={!iconAccessibilityLabel}
accessible={iconAccessibilityLabel ? true : undefined}
aria-label={iconAccessibilityLabel}
>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

could we add role="img" when iconAccessibilityLabel is provided?

this View renders as a generic <div> on web
react native web doesn't implement accessible prop (source) and a generic element cannot have an accessible name. that's why wrapper’s aria-label isn't guaranteed to label nested image ((source)

Suggested change
<View
testID={`${testID ?? 'banner'}-icon`}
style={styles.icon}
aria-hidden={!iconAccessibilityLabel}
accessible={iconAccessibilityLabel ? true : undefined}
aria-label={iconAccessibilityLabel}
>
<View
testID={`${testID ?? 'banner'}-icon`}
style={styles.icon}
aria-hidden={!iconAccessibilityLabel}
accessible={iconAccessibilityLabel ? true : undefined}
aria-label={iconAccessibilityLabel}
role={iconAccessibilityLabel ? 'img' : undefined}
>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thanks for addressing 🙏

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this one was already in, just never closed it. role="img" + label only when iconAccessibilityLabel is set, otherwise hidden.

Comment thread src/components/Banner.tsx Outdated
maxFontSizeMultiplier={maxFontSizeMultiplier}
{exited ? null : (
<Animated.View
testID={`${testID ?? 'banner'}-content`}

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Only derive these when testID is set - the snapshots show banner-content, banner-row and banner-message on banners that were given no testID. Default test ids conflict with the user's own (#4998).

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no inner test IDs at all now, same as #5099. only the passed testID lands on the root.

Comment thread src/components/Banner.tsx
const hasLiveRegion = () => Platform.OS === 'android' || Platform.OS === 'web';

// a nested <Text> would otherwise be dropped from the announcement
const extractText = (node: React.ReactNode): string =>

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

child.props.children breaks on any child that doesn't render its own children, so <Banner><Message /></Banner> announces nothing on iOS. React.Children is the composition problem v6 is meant to remove (#4954) - what's the alternative here?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yep, and it looks like it's not just iOS. Both the android and web live regions will go empty too. Checked it: zero announceForAccessibility calls on iOS, empty announcer on Android, visible text renders fine. dead silent on every platform. Thanks for bringing that up!

i see it liek that:

  • add messageAccessibilityLabel, matching iconAccessibilityLabel in this PR
  • keep extraction as the default so plain text keeps working
  • warn in dev when extraction is empty but children are not

React.Children stays as best effort with an opt out, not as main mechanism. but i'm happy to drop extraction entirely or park this for v6 instead. any preference?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

still there on purpose, depends on the children API question John raised below. proposal is a message: string prop, then the walk goes away.

Comment thread src/components/Banner.tsx Outdated
React.useEffect(() => {
const focused = focusedAction.current;

if (focused === null || focused < actionCount) {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

focusedAction.current isn't cleared on hide - focused < actionCount returns first. Hide, then show with actions={[]}, and focus jumps to the message. The test that covers this keeps one action, so it short-circuits too.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

index tracking is gone, focus is tracked by action key and cleared on hide. added a test for your repro (hide, show again with actions={[]}) in be1e40d.

Comment thread src/components/Banner.tsx Outdated
textColor={colors.primary}
theme={theme}
{...others}
touchableRef={mergeRefs(

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mergeRefs returns a new callback every render, so React detaches and reattaches each action ref on every commit — a consumer's touchableRef callback gets null then the node each time. Maybe try to memoize it.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed, one cached ref callback per action key. it changes only when that action's touchableRef changes.

@MikitasK MikitasK left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM 👌

Comment thread src/components/Banner.tsx
Comment on lines +423 to +429
<View
testID={`${testID ?? 'banner'}-icon`}
style={styles.icon}
aria-hidden={!iconAccessibilityLabel}
accessible={iconAccessibilityLabel ? true : undefined}
aria-label={iconAccessibilityLabel}
>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thanks for addressing 🙏

@satya164
satya164 requested a balanced review from Copilot September 15, 2026 20:33

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@satya164

Copy link
Copy Markdown
Contributor

Review by Claude

Web

A banner without actions loses its bottom spacing and the icon moves to the vertical center.

Steps: render <Banner visible icon={...}> with a message that wraps to 3 or more lines and no actions.

What happens: the text sits 8px above the bottom edge (it was 16px on the base branch), so the top spacing (24px) and the bottom spacing no longer match. The icon is centered on the text block instead of aligned with the first lines.

What should happen: the same spacing and icon position as before, since the PR description does not list this as a change.

Base branch:

Web, base branch: banner without actions

This PR:

Web, this PR: banner without actions

(via Claude, verify if it makes sense)

Android

The same spacing and icon change for a banner without actions.

Steps: the same as on web.

What happens: the last line of text is 8px from the bottom edge, and the icon is centered on the text.

What should happen: 16px bottom spacing, as on the base branch.

Android, this PR: banner without actions

(via Claude, verify if it makes sense)

@satya164 satya164 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review by Claude

  • extractText (line 38) still reads child.props.children through React.Children.toArray, and the open thread on it waits for a decision. The project rule is to avoid the Children API and element inspection, so the extraction should go. On Android and web the live region can render {children} itself instead of a string, so it announces whatever the children render, including <Message />. iOS needs a string for announceForAccessibilityWithOptions, so take it from an explicit prop there, such as the messageAccessibilityLabel proposed in the thread.
  • The branch conflicts with main in Banner.tsx, the example, the tests and the snapshot. main already moved the example banner below the app bar (#5061), so the rebase should drop the onLayout padding and the absolute position from the example. (via Claude, verify if it makes sense)

Comment thread src/components/Banner.tsx
</Text>
</View>
</View>
{visibleActions.length ? (

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A banner without actions now ends 8px below the text instead of 16px. The empty actions row used to add 8px of margin, and nothing replaces it now. Multi-line messages also get the icon centered on the text because of alignItems: 'center' on body (line 537). Before, the icon sat at the top. Web and Android screenshots are in this comment.

Web, this PR: banner without actions

Add 8px of bottom margin to content when there are no actions, and keep the icon at the top unless the change is intended. The PR description does not list either change. (via Claude, verify if it makes sense)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

both unintended, fixed. without actions it now renders exactly like main again (16px below the text, icon at the top), before/after screenshots on web are pixel identical.

Comment thread src/components/Banner.tsx Outdated
// and the tab order. native ignores the unknown prop
const inertProps: { inert?: boolean } = visible ? {} : { inert: true };

const stacked = !row.measured || row.width < COMPACT_BREAKPOINT;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On wide screens the first render always stacks the actions, because row is not measured yet. The next render moves them inline. On web at 1280px wide the banner is 126px tall for 2 frames and then shrinks to 72px, so the content below it jumps on every mount.

The comment on COMPACT_BREAKPOINT cites the md3 window size class, which uses the window width. useWindowDimensions gives that value in the first render and removes the useLayout state and the extra render:

Suggested change
const stacked = !row.measured || row.width < COMPACT_BREAKPOINT;
const { width: windowWidth } = useWindowDimensions();
const stacked = windowWidth < COMPACT_BREAKPOINT;

This also needs the useWindowDimensions import and drops onRowLayout. If the layout must follow the banner's own width, keep the row hidden until it is measured instead. (via Claude, verify if it makes sense)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

went with useWindowDimensions, no measuring, no jump. trade-off: a banner narrower than the window still goes inline at 600+. noted in the migration guide, ok?

Comment thread src/components/Banner.tsx Outdated
Comment on lines +396 to +397
const messageFocusProps: Pick<ViewProps, 'tabIndex' | 'accessible'> =
Platform.OS === 'web' ? { tabIndex: -1 } : { accessible: true };

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On Android, accessible: true makes the message View focusable, so a hardware keyboard Tab stops on the message text, which is not interactive.

The focus move for a removed action also does not reach keyboard users on Android. Steps: give the banner 2 actions where the second one removes itself, Tab to it with a hardware keyboard and press Enter. Keyboard focus goes to the first focusable view on the screen (here, the message of another banner) instead of the remaining action. setAccessibilityFocus in focusNode moves screen reader focus, not keyboard focus.

Leave accessible unset on native, since the Text is already one accessibility element. Then either move keyboard focus on native too, or limit the focus handling to web, where .focus() works and findNodeHandle is not needed. (via Claude, verify if it makes sense)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

accessible is gone from the message and the live region, Android Tab skips the message now.

on focus:

  • keyboard focus can't be moved from JS on native (focus() on a View is a no-op on 0.88, iOS never fires onFocus), so no native keyboard rescue
  • screen readers can: sendAccessibilityEvent(node, 'focus') after the removed action was pressed, only with a screen reader on
  • web uses plain .focus()

checked on iPhone VoiceOver, S23 TalkBack and Chromium, table in the first comment.

Comment thread src/components/Banner.tsx Outdated
]}
>
<View
testID={subTestID('row')}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

content, row and announcer are internal wrappers, and their test IDs exist only so the tests can reach them. The reflow tests then assert flexDirection on banner-row, which is an internal style. The project test rules ask for public output instead: query the live region by role (status or alert), and the message and actions by text or their public IDs. (via Claude, verify if it makes sense)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done, no internal test IDs. region found by role, the rest by text and role. dropped the reflow tests that read flexDirection, layout is in the video.

Comment thread example/src/Examples/BannerExample.tsx Outdated
Comment on lines +56 to +60
<FAB
icon="alert"
style={styles.urgentFab}
onPress={() => setUrgent(!urgent)}
/>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This FAB has no label, so TalkBack and VoiceOver read it as an unlabelled button. This toggle exists to test screen reader output, so give it a label that also says what it does:

Suggested change
<FAB
icon="alert"
style={styles.urgentFab}
onPress={() => setUrgent(!urgent)}
/>
<FAB
icon="alert"
aria-label={urgent ? 'Make banner not urgent' : 'Make banner urgent'}
style={styles.urgentFab}
onPress={() => setUrgent(!urgent)}
/>

(via Claude, verify if it makes sense)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

used your wording, and labelled the eye FAB too.

@Doberjohn Doberjohn added this to the 6.0.0 milestone Oct 30, 2026
@Doberjohn

Copy link
Copy Markdown
Collaborator

One thing to settle while Banner is reworked: the message is still wrapped in <Text>, so anything that isn't text inside it misbehaves. The known case is #4178: on iOS, a TextInput inside a Banner loses focus on every keystroke.

Either Banner supports non-text children (render elements outside the Text), or we document that children are text only. #4179 tried the first on 5.x but broke Text and fragment children. Whichever way 6.0 goes, 5.x will follow.

@Doberjohn Doberjohn modified the milestones: 6.0.0, 6.0.0-beta.0 Nov 12, 2026
@lukemorawski
lukemorawski force-pushed the feat/banner-a11y-inert-when-hidden branch from d347dc3 to 4c8a76f Compare November 18, 2026 14:14
@lukemorawski
lukemorawski force-pushed the feat/banner-a11y-inert-when-hidden branch from 4c8a76f to f1100c8 Compare November 18, 2026 15:37
@lukemorawski lukemorawski changed the title fix(banner): make hidden content inert and fix live region semantics feat(banner)!: make hidden content inert and fix live region semantics Nov 18, 2026
@lukemorawski

lukemorawski commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Breaking changes (all in the migration guide)

  • Children unmount once hidden.
  • At most 2 actions, extras dropped with a dev warning.
  • Actions sit inline from 600dp. The breakpoint follows the window, not the banner.
  • Default role is status, urgent gives alert. Tests using getByRole('alert') need urgent.
  • Announced only on hidden to visible, not on mount or when urgent flips.

Focus rescue, measured on the real Banner

Removed Web (Chromium) iPhone 12 VoiceOver S23 FE TalkBack
B of A, B C C C
C of A, C A A A
only action message message message
hide back to opener no restore no restore

Web uses .focus() (message has tabIndex={-1}). Native uses sendAccessibilityEvent when a screen reader is on and the action was pressed in the last second, since RN does not report screen reader focus. Without the rescue, web drops to body and TalkBack goes to the next node. Android hardware Tab skips the message.

Known gaps

  • Native hide does not restore focus (S23 jumps to Back). A restoreFocusRef prop can fix it in a follow-up.
  • No rescue for hardware keyboards on native: focus() on a View is a no-op on RN 0.88 and iOS never fires onFocus.
  • Real Safari not tested, WebKit and Firefox only via Playwright.
  • The message uses AnimatedText to get a host ref. A message that is a single Paper <Text variant> keeps bodyMedium on the outer line.
  • iOS still builds the announcement with extractText, until the children API question below is settled.

Media

web, only action removed, focus goes to the message:

web-after-focus-rescue-only-C.webm

web, hide with focus inside, focus goes back to the opener:

web-after-focus-return-on-hide.webm

TalkBack (emulator), C removed, cursor on A:
TalkBack cursor on Action A

@lukemorawski

Copy link
Copy Markdown
Contributor Author

@satya164 re your review: rebased, animation is on Reanimated now. rest is answered in the threads. extraction stays until the children API is decided.

@lukemorawski

Copy link
Copy Markdown
Contributor Author

@Doberjohn re the <Text> question: i'd go with a third option: message: string instead of children, plus an optional content slot rendered outside the Text and outside the live region.

<Banner visible message="Payment failed." actions={actions} />
<Banner visible message="Confirm your email" content={<TextInput />} />

cost: breaking, but mechanical, and old usage becomes a type error. rich inline text in the message goes (bold, links), content covers it.

fallback if you don't want to break it in 6.0: keep text children, add content and messageAccessibilityLabel.

which one? i'll do it in this PR.

also: does #5016 land before this one? both touch the Banner animation.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

refactor(banner): make hidden content inert and fix live region semantics

6 participants