React Reference ยท Props and Attributes
React focus events (onFocus and onBlur)
Reference for React focus events: onFocus and onBlur bubble, relatedTarget tells you where focus went, and onFocusCapture lets parents listen first.
onFocus runs when an element receives keyboard focus and onBlur runs when it loses it. You can put them on form fields, buttons, links, anything with a tabIndex, and on elements that merely contain focusable children.
React's versions differ from the plain DOM events in one important way: they bubble. The native focus and blur events do not, but React listens to focusin and focusout underneath. A handler on a <fieldset> or <div> therefore runs whenever any field inside it gains or loses focus. That makes "is focus anywhere inside this group?" easy to answer.
<input onFocus={(e) => console.log('focused', e.target.name)} onBlur={(e) => console.log('left', e.target.name)} />
Try it
Syntax
<element onFocus={(event: React.FocusEvent) => void} onBlur={(event: React.FocusEvent) => void} onFocusCapture={(event: React.FocusEvent) => void} onBlurCapture={(event: React.FocusEvent) => void} />
| Name | Description |
|---|---|
event.target |
The element that actually gained or lost focus (may be a descendant of the element with the handler). |
event.currentTarget |
The element your handler is attached to. |
event.relatedTarget |
For onFocus, the element that lost focus; for onBlur, the element about to receive it. null when focus comes from or goes to outside the page, or to nothing. |
event.nativeEvent |
The underlying FocusEvent (type focusin or focusout). |
Returns: nothing. Focus events cannot be cancelled, so preventDefault() has no effect on them.
Edge cases: relatedTarget can be null even when focus moves between two elements of your page, for example when the target is not focusable by mouse in some browsers. Treat null as "left the group".
Usage notes
- Bubbling is React's behavior. A listener on a wrapper sees focus changes of all descendants. Compare
event.targetandevent.currentTargetif you only care about the wrapper itself. - Focus-within pattern. In
onBlur, checke.currentTarget.contains(e.relatedTarget). Without that test, moving from one field to the next inside the group flickers the state to "outside" and back. For pure styling, the CSS:focus-withinselector needs no JavaScript at all. - Order of events. When focus moves from A to B,
bluron A runs beforefocuson B. - Capture versions.
onFocusCaptureandonBlurCapturerun on the way down, before the target's own handler. Use them when a parent must act first. - Not every element is focusable. A
<div>receives focus events only if it has atabIndex. UsetabIndex={0}for custom widgets and-1for elements you focus from code. - Do not validate in a way that traps users. Showing an error on blur is fine; moving focus back to the field is hostile to keyboard and screen reader users.
- Focus from code. Call
ref.current.focus()in an event handler or effect; it fires the same events. See useRef with DOM nodes. autoFocusfiresonFocustoo, during the commit when the element mounts.