[LG-5608] feat(modal): restore initialFocus prop with enhanced functionality #3202
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…nstead adds guidance comment
🦋 Changeset detectedLatest commit: f6058df The changes in this PR will be included in the next version bump. This PR includes changesets to release 6 packages
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 |
There was a problem hiding this comment.
Pull Request Overview
This PR restores the initialFocus prop to the Modal component that was prematurely removed in v20. The prop now supports enhanced functionality including React refs, CSS selectors, automatic behavior, and the ability to disable focus management entirely.
Key changes:
- Restores
initialFocusprop with support for"auto"(default), string selectors, React refs, andnull - Updates focus priority:
initialFocusprop →autoFocusattribute → first focusable element - Updates the
modal-v20codemod to preserve theinitialFocusprop instead of removing it
Reviewed Changes
Copilot reviewed 17 out of 17 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
tools/codemods/src/codemods/modal-v20/transform.ts |
Updates codemod to preserve initialFocus prop and add guidance comment instead of removing it |
tools/codemods/src/codemods/modal-v20/tests/transform.spec.ts |
Removes test for remove-initialFocus behavior that is no longer applicable |
tools/codemods/src/codemods/modal-v20/tests/remove-initialFocus.output.jsx |
Deletes expected output file for removed initialFocus test |
tools/codemods/src/codemods/modal-v20/tests/remove-initialFocus.input.jsx |
Deletes input file for removed initialFocus test |
tools/codemods/src/codemods/modal-v20/tests/handle-aliases.output.jsx |
Updates expected output to preserve initialFocus props with new guidance comment |
tools/codemods/src/codemods/modal-v20/tests/filter-packages.output.jsx |
Updates expected output to preserve initialFocus props with new guidance comment |
tools/codemods/README.md |
Updates codemod documentation to reflect that initialFocus is now preserved |
packages/modal/src/utils/focusModalChildElement.ts |
Adds support for the restored initialFocus parameter with enhanced functionality |
packages/modal/src/utils/focusModalChildElement.spec.ts |
Adds comprehensive tests for all initialFocus scenarios and priority ordering |
packages/modal/src/Modal/ModalView.tsx |
Integrates initialFocus prop and passes it to focus utility function |
packages/modal/src/Modal/Modal.types.ts |
Adds type definition and comprehensive documentation for initialFocus prop |
packages/modal/src/Modal/Modal.spec.tsx |
Adds extensive test coverage for all initialFocus behaviors and edge cases |
packages/modal/UPGRADE.md |
Updates upgrade guide to reflect that initialFocus is available again in v20.2+ |
packages/modal/README.md |
Updates documentation with initialFocus prop details and focus behavior explanation |
packages/modal/CHANGELOG.md |
Updates changelog to clarify initialFocus removal and restoration timeline |
.changeset/modal-initial-focus-revert.md |
Adds changeset documenting the restoration of initialFocus prop |
.changeset/codemods-modal-v20-update.md |
Adds changeset documenting codemod updates |
|
Size Change: +70 B (0%) Total Size: 1.59 MB
ℹ️ View Unchanged
|
kraenhansen
reviewed
Oct 9, 2025
kraenhansen
reviewed
Oct 9, 2025
| * 4. If `initialFocus` is `null`, no automatic focus occurs | ||
| * | ||
| * @param modalElement - The modal dialog element | ||
| * @param initialFocus - Focus target ("auto", selector, ref, or null) |
There was a problem hiding this comment.
My initial expectation would be to pass false instead of null here to disable the initial focus behavior 🤔
There was a problem hiding this comment.
I could be down for false over null. It was also my natural inclination but was worried it could be confusing since true is not a valid value. I will solicit feedback with the team on this as well. Appreciate your feedback
kraenhansen
reviewed
Oct 9, 2025
kraenhansen
approved these changes
Oct 9, 2025
There was a problem hiding this comment.
Lots of great stuff! Thanks for the fast turnaround on this!
Did you consider initialFocus={false} instead of initialFocus={null} to signal disabling the auto-focus behavior all together? I don't feel strongly for either way, so not a blocker.
I personally feel the focusModalChildElement tests are getting a bit lengthy and hard to follow with the way the mocks are used. This is definitely not a blocker.
tsck
approved these changes
Oct 14, 2025
github-merge-queue
bot
removed this pull request from the merge queue due to failed status checks
github-merge-queue
bot
removed this pull request from the merge queue due to failed status checks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
✍️ Proposed changes
This PR restores the
initialFocusprop to the Modal component that was prematurely removed in v20 without proper migration paths. The prop now supports enhanced functionality including React refs, CSS selectors (legacy support), an"auto"default behavior, and the ability to disable focus management withnull.Key changes:
initialFocusprop with support for"auto", string selectors, React refs, andnullinitialFocusprop →autoFocusattribute → first focusable elementmodal-v20codemod to preserveinitialFocusand add migration guidance🎟️ Jira ticket: LG-5608
✅ Checklist
pnpm changesetand documented my changes🧪 How to test changes
Test auto focus (default behavior):
initialFocusTest focus with string selector:
initialFocus="#my-button"on a Modalid="my-button"receives focusTest focus with ref:
useRef<HTMLButtonElement>(null)initialFocus={myRef}Test disabled focus:
initialFocus={null}on a ModalTest priority order:
initialFocusprop andautoFocusattribute on different elementsinitialFocustakes priority overautoFocusTest fallback behavior:
initialFocusto a non-existent selectorautoFocusattribute, then first focusable element