fix(clerk-js): Ensure errors are being read to screen readers #7111

alexcarpenter · 2025-10-31T14:52:18Z

Description

Introduces a live region that updates when feedback changes to ensure messages are read live to the user as they change
Preserves aria-describeby to ensure when tabbing through fields that the feedback message is read on focus

Why Both Are Needed

Visually hidden element: Provides real-time announcements as you type (via aria-live)
Visual elements: Provide context when navigating - when a screen reader user tabs to the password field, it reads: "Password field, [error message]" using the aria-describedby connection

So you get:

While typing: "Password too short" → "Add uppercase letters" (from live region)
When focusing field: "Password, Password too short" (from aria-describedby)

fixes USER-3837

Testing

open VO and within the password input, start typing to trigger the different feedback
- acceptance: the contents of the feedback should be immediately read to screen reader
submit an invalid form which renders error feedback on fields. open VO and tab through the fields
- acceptance: the error messages should be read on focus due to the aria-describedby connection to the inputs

Screen.Recording.2025-10-31.at.1.45.07.PM.mov

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

changeset-bot · 2025-10-31T14:52:22Z

🦋 Changeset detected

Latest commit: ab795fb

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@clerk/clerk-js	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-expo	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2025-10-31T14:52:25Z

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

Project	Deployment	Preview	Comments	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Comment	Oct 31, 2025 3:11pm

coderabbitai · 2025-10-31T14:52:29Z

Walkthrough

The change introduces a dedicated ARIA live region to the FormControl component for announcing feedback messages to screen readers. The visually hidden live region replaces aria-live semantics previously applied to individual feedback components. Tests are updated to verify the live region's content rather than element attributes.

Changes

Cohort / File(s)	Change Summary
Release metadata `.changeset/puny-places-shine.md`	New changeset recording a patch release for @clerk/clerk-js documenting the addition of an ARIA live region for feedback message announcements.
FormControl component `packages/clerk-js/src/ui/elements/FormControl.tsx`	Introduces a visually hidden live region (Span element) preceding the feedback container to announce feedback changes to screen readers. Adds Span import from customizables and visuallyHidden utility. Removes aria-live semantics from individual InfoComponentA/B feedback components.
Component test `packages/clerk-js/src/ui/elements/__tests__/PlainInput.test.tsx`	Updates test case to verify screen-reader-only live region content instead of aria-live attributes on visible elements. Adjusts assertions to detect the visually hidden region by positioning and verify its content during feedback transitions.

Sequence Diagram

sequenceDiagram
    participant User
    participant FormControl
    participant LiveRegion as Live Region<br/>(aria-live)
    participant ScreenReader as Screen Reader

    User->>FormControl: Submit form / trigger validation
    FormControl->>FormControl: Feedback state changes
    FormControl->>LiveRegion: Update content with new feedback
    LiveRegion->>ScreenReader: Content changed (polite)
    ScreenReader->>User: Announces feedback message

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

FormControl.tsx: Review the live region implementation, verify visuallyHidden styling is correctly applied, and confirm aria-live removal from children doesn't impact other functionality.
PlainInput.test.tsx: Verify test assertions correctly target the new live region and that visibility-based checks cover the intended feedback transitions.

Poem

🐰 A live region takes the stage,
Hidden from sight but heard with grace,
Screen readers speak the feedback's way,
When changes dance from night to day! ✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run `@coderabbitai generate docstrings` to improve docstring coverage.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The PR title "fix(clerk-js): Ensure errors are being read to screen readers" clearly and concisely describes the primary change in the changeset. It directly aligns with the main objective of the PR, which is to fix screen reader announcements for form errors by adding a live region. The title is specific enough for a teammate to understand the key change without being overly detailed, and it accurately reflects the core problem being solved in the linked issue (USER-3837).
Linked Issues Check	✅ Passed	The code changes directly address the primary objective stated in linked issue USER-3837, which is to ensure form errors are announced by screen readers. The PR implements this by introducing a screen-reader live region (aria-live="polite") in FormControl.tsx that announces feedback changes when they occur, and the updated tests verify that this live region correctly announces error and success messages. The changes also preserve aria-describedby for field focus scenarios, ensuring comprehensive screen reader support as described in the PR objectives.
Out of Scope Changes Check	✅ Passed	All code changes are directly scoped to the fix for screen reader announcements. The changeset file documents the patch release, FormControl.tsx implements the live region solution for announcing feedback changes, and the test updates verify the new functionality works correctly. No extraneous refactoring, unrelated modifications, or scope creep are evident in the changeset.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch alexcarpenter/user-3837-form-errors-not-being-announced-by-screen-readers

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

alexcarpenter · 2025-10-31T16:10:13Z

!snapshot

clerk-cookie · 2025-10-31T16:12:40Z

Hey @alexcarpenter - the snapshot version command generated the following package versions:

Package	Version
@clerk/agent-toolkit	0.1.45-snapshot.v20251031161044
@clerk/astro	2.14.3-snapshot.v20251031161044
@clerk/backend	2.19.2-snapshot.v20251031161044
@clerk/chrome-extension	2.7.11-snapshot.v20251031161044
@clerk/clerk-js	5.103.2-snapshot.v20251031161044
@clerk/elements	0.23.76-snapshot.v20251031161044
@clerk/clerk-expo	2.17.4-snapshot.v20251031161044
@clerk/expo-passkeys	0.4.13-snapshot.v20251031161044
@clerk/express	1.7.44-snapshot.v20251031161044
@clerk/fastify	2.5.1-snapshot.v20251031161044
@clerk/localizations	3.26.5-snapshot.v20251031161044
@clerk/nextjs	6.34.2-snapshot.v20251031161044
@clerk/nuxt	1.11.3-snapshot.v20251031161044
@clerk/clerk-react	5.53.5-snapshot.v20251031161044
@clerk/react-router	2.1.7-snapshot.v20251031161044
@clerk/remix	4.13.10-snapshot.v20251031161044
@clerk/shared	3.30.0-snapshot.v20251031161044
@clerk/tanstack-react-start	0.26.6-snapshot.v20251031161044
@clerk/testing	1.13.10-snapshot.v20251031161044
@clerk/themes	2.4.31-snapshot.v20251031161044
@clerk/types	4.97.0-snapshot.v20251031161044
@clerk/vue	1.14.10-snapshot.v20251031161044

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/agent-toolkit

npm i @clerk/[email protected] --save-exact

@clerk/astro

npm i @clerk/[email protected] --save-exact

@clerk/backend

npm i @clerk/[email protected] --save-exact

@clerk/chrome-extension

npm i @clerk/[email protected] --save-exact

@clerk/clerk-js

npm i @clerk/[email protected] --save-exact

@clerk/elements

npm i @clerk/[email protected] --save-exact

@clerk/clerk-expo

npm i @clerk/[email protected] --save-exact

@clerk/expo-passkeys

npm i @clerk/[email protected] --save-exact

@clerk/express

npm i @clerk/[email protected] --save-exact

@clerk/fastify

npm i @clerk/[email protected] --save-exact

@clerk/localizations

npm i @clerk/[email protected] --save-exact

@clerk/nextjs

npm i @clerk/[email protected] --save-exact

@clerk/nuxt

npm i @clerk/[email protected] --save-exact

@clerk/clerk-react

npm i @clerk/[email protected] --save-exact

@clerk/react-router

npm i @clerk/[email protected] --save-exact

@clerk/remix

npm i @clerk/[email protected] --save-exact

@clerk/shared

npm i @clerk/[email protected] --save-exact

@clerk/tanstack-react-start

npm i @clerk/[email protected] --save-exact

@clerk/testing

npm i @clerk/[email protected] --save-exact

@clerk/themes

npm i @clerk/[email protected] --save-exact

@clerk/types

npm i @clerk/[email protected] --save-exact

@clerk/vue

npm i @clerk/[email protected] --save-exact

fix(clerk-js): Ensure errors are being read to screen readers

2e3f58c

clerk-cookie added the clerk-js label Oct 31, 2025

vercel bot deployed to Preview October 31, 2025 14:53 View deployment

add changeset

ab795fb

vercel bot deployed to Preview October 31, 2025 15:11 View deployment

alexcarpenter marked this pull request as ready for review October 31, 2025 15:33

alexcarpenter requested a review from Ephem October 31, 2025 15:55

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(clerk-js): Ensure errors are being read to screen readers #7111

fix(clerk-js): Ensure errors are being read to screen readers #7111

Uh oh!

alexcarpenter commented Oct 31, 2025 •

edited

Loading

Uh oh!

changeset-bot bot commented Oct 31, 2025 •

edited

Loading

Uh oh!

vercel bot commented Oct 31, 2025 •

edited

Loading

Uh oh!

coderabbitai bot commented Oct 31, 2025 •

edited

Loading

Uh oh!

alexcarpenter commented Oct 31, 2025

Uh oh!

clerk-cookie commented Oct 31, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

fix(clerk-js): Ensure errors are being read to screen readers #7111

Are you sure you want to change the base?

fix(clerk-js): Ensure errors are being read to screen readers #7111

Uh oh!

Conversation

alexcarpenter commented Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Why Both Are Needed

Testing

Checklist

Type of change

Uh oh!

changeset-bot bot commented Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel bot commented Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram

Estimated code review effort

Poem

Pre-merge checks and finishing touches

Uh oh!

alexcarpenter commented Oct 31, 2025

Uh oh!

clerk-cookie commented Oct 31, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

alexcarpenter commented Oct 31, 2025 •

edited

Loading

changeset-bot bot commented Oct 31, 2025 •

edited

Loading

vercel bot commented Oct 31, 2025 •

edited

Loading

coderabbitai bot commented Oct 31, 2025 •

edited

Loading