> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overflow.co/llms.txt
> Use this file to discover all available pages before exploring further.

# onFocus and onBlur

> Element-scoped focus events. Moving between sub-fields does not re-fire.

`onFocus` fires when keyboard focus enters an element as a whole. `onBlur` fires when focus leaves the element entirely. Both are element-scoped, not field-scoped.

## Payload

```typescript theme={null}
type OverflowFocusEvent<T> = { elementType: T };
type OverflowBlurEvent<T>  = { elementType: T };
```

## Element-scoped, not field-scoped

Moving between sub-fields of a compound element (for example, from `line1` to `city` in `billingAddress`, or from the card number to the expiration inside `card`) does not produce intervening blur and focus pairs. Each element fires `onFocus` once when focus first enters its DOM subtree, and `onBlur` once when focus leaves the subtree entirely.

## Example

```javascript theme={null}
overflow.card()
  .on('onFocus', () => log('card focused'))
  .on('onBlur',  () => log('card blurred'))
  .mount('#card');
```

## Delivery sources

Focus can be delivered by keyboard, mouse, touch, or programmatic `element.focus()`. All three go through the same DOM plumbing and produce a single `onFocus` when net focus enters, and a single `onBlur` when net focus leaves.

## Per-element behavior

* **Single-input elements** (`email`, `submitButton`, `phone`, single-mode `fullName`) attach native focus and blur directly to their underlying input, forwarding one-to-one.
* **Multi-input elements** (split-mode `fullName`, `billingAddress`, `shippingAddress`, manual-mode `bank`, `checkout`) wire focus tracking to a wrapper element and suppress same-subtree transitions.
* **`card`** runs an internal focused-field counter. Secured card fields (card number, expiration, security code) emit per-field focus signals that increment or decrement the counter; the holder-name and postal-code inputs contribute through native focus events on the same counter. A microtask boundary collapses the synchronous blur-to-focus traffic the browser fires when tab-switching between sub-fields, so only net-zero-to-at-least-one transitions emit element-level events.
* **`bank`** fires focus and blur only in manual mode. Address-lookup mode has nothing focusable beyond the launch button (kept out of scope so the wallet-style "click to modal" flow does not fire blur or focus pairs around the modal).
* **`applePay` / `googlePay`** wire focus and blur to the mount container. Focus events from inside the wallet-rendered button do not necessarily bubble out of the wallet's rendering surface, so consumers should not rely on wallet focus events firing on every device.

## Use for analytics, not validation

Focus and blur are good for analytics ("shopper touched the card field"), micro-interactions, and side effects like autofilling a related field. Do not use them for validity gating; drive that off `onChange.complete`.

## See also

* [`onChange`](/payment-elements/events/on-change)
* [`onEscapeKeyPressed`](/payment-elements/events/on-escape-key-pressed)