React18 String Refs

React 18 string refs migration

Convert deprecated React string refs into explicit refs by pairing every ref="name" assignment with its this.refs.name access, choosing the correct fixed, dynamic, callback, or child-component pattern, and producing a migration summary.

When to invoke

• "Migrate these React string refs."
• "Fix React 18.3.1 warnings about string refs."
• "Prepare this class component for React 19 refs."
• "Convert this.refs usage to createRef."
• "Handle string refs inside a list."
• "Fix the multiple-refs-in-list migration."

String ref inventory

String refs use ref="myInput" or ref='myInput' in JSX and access the node through this.refs.myInput. They were deprecated in React 16.3, warn in React 18.3.1, and are removed in React 19.

Run both scans and migrate each pair together:

# Find all string ref assignments in JSX
grep -rn 'ref="' src/ --include="*.js" --include="*.jsx" | grep -v "\.test\."

# Find all this.refs accessors
grep -rn "this\.refs\." src/ --include="*.js" --include="*.jsx" | grep -v "\.test\."

Also scan for single-quoted refs when the codebase uses them:

grep -rn "ref='" src/ --include="*.js" --include="*.jsx" | grep -v "\.test\."

Migration pattern map

Read references/patterns.md when implementing the full before/after examples for single-ref, multiple-refs, list-refs, callback-refs, and forwarded-refs.

Migration rules

1. Pair every ref="name" with every this.refs.name usage before editing.
2. Add refName = React.createRef(); as a class field, or initialize it in the constructor when the project does not use class fields.
3. Replace ref="refName" with ref={this.refName} in JSX.
4. Replace this.refs.refName with this.refName.current everywhere.
5. Add null checks such as this.refName.current?.focus() when the old code could run before mount or after unmount.
6. For list refs, key the ref collection by the same stable identity used for rendering, such as tab.id, not by a transient index unless the list is truly static.
7. For callback refs, remember that this.tabRefs[i] is the element itself; do not append .current.

Progressive disclosure and bundled resources

• references/patterns.md: complete before/after migrations for single DOM refs, multiple refs, dynamic list refs, callback refs, and child component refs.

Gotchas

• Do not migrate only one side: changing ref="name" without changing this.refs.name, or the reverse, leaves broken runtime access.
• Dynamic refs are not fixed refs: ref={`tab_${i}`} needs a ref collection, not one tabRef field.
• Callback refs store nodes directly: this.inputEl?.focus() is correct; this.inputEl.current is not.
• Child refs may require child changes: a ref on <MyInput /> does not automatically point at the inner <input> unless the child forwards or accepts it.

Output template

## React string ref migration

**Status:** migrated | planned | blocked
**Scope:** `<files or component>`

| Component | String refs found | Replacement pattern | Notes |
| --- | --- | --- | --- |
| `<Component>` | `ref="name"`, `this.refs.name` | `React.createRef()` | `<null checks, child changes, or list key>` |

**Validation**
- String ref scan: `<remaining hits or none>`
- `this.refs` scan: `<remaining hits or none>`
- Tests/build: `<command and result, or not run>`

Quality gate

• Every ref="name" or ref='name' hit was paired with matching this.refs.name access before editing.
• Fixed refs use distinct React.createRef() fields or constructor assignments.
• Dynamic list refs use a Map, object, or callback collection keyed by a stable identity.
• Callback ref migrations do not incorrectly use .current.
• Child component refs update the child with forwardRef for React 18 or direct ref prop handling for React 19.
• references/patterns.md was consulted for any non-trivial pattern.
• Follow-up scans show no remaining string refs in the migrated scope, or remaining hits are explicitly justified.