# onFocus, onFocusWithin, onBlurWithin

> `onFocus` runs an action when the element itself takes keyboard focus — the mirror of `onBlur` — and makes a plain element a stop in the tab order so it can. `onFocusWithin` runs when focus enters the element or anything inside it from outside; `onBlurWithin` when focus leaves all of it. Together with `onEscape` they are the keyboard half of hover: content a pointer opens on hover opens on focus too, and closes on Escape and when focus leaves.

<!-- id: ui-on-focus · area: ui · stability: stable · html: https://osysharp.com/reference/ui/on-focus/ -->

## Summary        {#summary}
Hover is a pointer's. Whatever a pointer opens on hover — a title, a definition, a preview — a keyboard user has to
be able to open too (WCAG 2.1.1 and 1.4.13), and to close again with Escape:

```osy syntax
component WhenSaid(string words, string exact) {
  bool open = false;
  action Show() { open = true; }
  action Hide() { open = false; }
  render {
    Box(position: Position.Relative,
        onPointerEnter: Show, onPointerLeave: Hide,          // the pointer
        onFocus: Show, onBlur: Hide,                         // the keyboard — and onFocus makes this Box a tab stop
        onEscape: open ? Hide : null) {                      // Escape closes it while it is open
      Text(words);
      if (open) { Box(role: UiRole.Tooltip, label: "Exact time") { Text(exact); } }
    }
  }
}
```

## Signature      {#signature}
```osy syntax
onFocus: <action>         // the element itself took focus
onFocusWithin: <action>   // focus entered the element or anything inside it, from outside it
onBlurWithin: <action>    // focus left the element and everything inside it
```

## Description    {#description}

### `onFocus` makes the element a tab stop   {#tab-stop}
A `Box` never takes focus on its own, so an `onFocus` on one would compile, wire up and never fire. Binding `onFocus`
to an action therefore makes a plain element a stop in the tab order (`tabindex="0"`, in the server's paint and the
browser's alike). Binding it to `null` makes none — so `onFocus: titled ? Show : null` is a stop only while there is
something to show. A `Button`, `Pressable`, `Input`, `TextArea`, `Select`, `Link` or frame is reachable already and
gets nothing extra.

### The group pair, and why `onBlurWithin` exists   {#within}
`onFocusWithin` and `onBlurWithin` judge a move by where focus came from or goes to. Moving from one control inside
the group to another is neither an entry nor a departure, so neither runs. That is the case `onBlur` cannot serve: a
popover opened from its owner has buttons of its own, and `onBlur` on the owner fires the moment focus steps into
them — the popover would close under the keyboard that came to use it. `onBlurWithin` on the group closes it only
when focus has left the owner and the popover both. Focus leaving to nowhere (the page itself, another window) counts
as leaving. A group that only listens is not itself a stop: its controls are.

### Not activations   {#not-guarded}
Like `onBlur`, none of the three is an activation: no busy spinner, no in-flight guard. Arriving somewhere is not a
submission.

### Closing on Escape   {#escape}
Pair an opened-on-focus surface with [onEscape](https://osysharp.com/reference/ui/on-escape/) bound only while it is open — `onEscape: open ? Hide : null` —
so it is the innermost Escape handler exactly while there is something to close, and the page's other Escape
handlers are untouched the rest of the time. Escape hides it without moving focus; arriving again opens it again.
A pure-CSS tip (`inside Button.Focus { Display = Display.Flex; }`, the kit's `KeyTip`) needs none of this: Escape
hides every such reveal by itself — see [[ui-styling#inside]].

### In a test   {#testing}
`Ui.Focus("3 h ago")` moves the keyboard to the stop holding that text, as a Tab arriving there would, and refuses a
control the keyboard cannot reach. Then `Assert.Focused`, `Ui.Press("Escape")` and `Ui.Press("Tab")` say the rest —
see [[testing-ui#focus]].

## Examples       {#examples}

```osy title="a definition that opens on hover and on focus" test app=ui-on-focus
component Term() {
  bool open = false;
  action Show() { open = true; }
  action Hide() { open = false; }
  render {
    Box(position: Position.Relative, onPointerEnter: Show, onPointerLeave: Hide, onFocus: Show, onBlur: Hide,
        onEscape: open ? Hide : null) {
      Text("WCAG");
      if (open) { Box(role: UiRole.Tooltip, label: "Meaning") { Text("Web Content Accessibility Guidelines"); } }
    }
  }
}
```

```osy title="a group that stays open while focus is anywhere inside it" test app=ui-on-focus-within
component Toolbar() {
  bool open = false;
  action Show() { open = true; }
  action Hide() { open = false; }
  render {
    Row(onFocusWithin: Show, onBlurWithin: Hide, onEscape: open ? Hide : null) {
      Button("Format", onPress: Show);
      if (open) {
        Button("Bold", onPress: Hide);
        Button("Italic", onPress: Hide);
      }
    }
  }
}
```

## See also       {#see-also}
- [onEscape](https://osysharp.com/reference/ui/on-escape/) — Escape as the dismiss gesture, page-wide while mounted
- [pointer](https://osysharp.com/reference/ui/pointer/) — `onPointerEnter`/`onPointerLeave`, the pointer half of hover
- [accessibility](https://osysharp.com/reference/ui/accessibility/) — what the platform does for keyboard and screen-reader users
- [Ui — drive the app's UI from a test](https://osysharp.com/reference/testing/ui/) — `Ui.Focus`, `Ui.Press("Tab")` and `Assert.Focused`
