Osy#betaRun it on Osyrin: osyrin.com

Reference / UI

onFocus, onFocusWithin, onBlurWithin

Box(onFocus: Open, onBlur: Close) · Box(onFocusWithin: Open, onBlurWithin: Close) — run an action when the keyboard arrives at an element or a group, and when it leaves

`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.

stable2 examples compiled by CIuieventskeyboardaccessibility

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:

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#

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#

onFocus makes the element a 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#

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#

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#

Pair an opened-on-focus surface with onEscape 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#

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#

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"); } }
    }
  }
}
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#

Related

onEscape

`onEscape` runs an action when the Escape key is pressed while the element is on screen. Unlike `onEnter` it is not…

pointer

`onPointerEnter` / `onPointerLeave` run an action when the pointer enters or leaves an element. They are the half of…

accessibility

Tags already give an element its role, focus and keyboard behaviour. The semantic props say the rest: `role:` for a…

Ui — drive the app's UI from a test

Drive the real UI from a test: navigate to a route, click what a person would click, and assert on what the screen…