Events

ntk delivers raw X11 events per window; react-x11 turns them into synthetic events dispatched over the drawn node tree with DOM-like semantics.

Dispatch

Hit test: front-to-back walk of the stacking-ordered tree (zIndex, then document order), respecting overflow clipping and pointerEvents — 'none' takes a node and everything in it out of the test, 'box-none' only the node itself, so its children are still targets and a point over its own area lands on what is behind it. A <glarea> is asked first: its surface is stacked above everything 2D in the window, and its children above the surface, so a point over one lands on the child under it or on the <glarea> — or, with 'box-none', on whatever the tree has behind the surface (elements.md).
Capture phase: on<Event>Capture handlers from the window down to the target.
Target + bubble phase: on<Event> handlers from the target up.
Default action: the element's built-in behavior (textinput editing, wheel scrolling, then Tab traversal) — skipped if any handler called ev.preventDefault().

Step 4 is a documented seam, not a privilege of the built-in elements: an element added with registerElement implements the same defaultKeyDown / defaultMouseDown / defaultMouseMove / … methods and gets the same ordering (extending.md). The wheel has one more layer than the rest: the node under the pointer gets defaultWheel first — for a pane whose wheel is a zoom rather than a scroll — and unless it consumes the event, the scroll chain walks outward from the target asking each node canScroll(deltaX, deltaY), which is how an element that scrolls content it painted joins in (extending.md).

ev.stopPropagation() stops the walk. Handlers always read from current props — they can never go stale.

When the response is painted

Discrete input paints from its own handler, in the same turn of the event loop as the press — not on the next frame. A click has exactly one visual answer (a button darkens, a caret lands, focus moves), so there is nothing a frame's wait could coalesce it with, and waiting would charge it up to a frame interval plus a server round trip on top of a paint that measures in the hundreds of microseconds. The dispatcher therefore lands React's discrete-priority commit and paints once the whole dispatch has unwound — the default action, your handlers and React's update all in one pass, never a half-updated frame followed by a second one.

Discrete means everything ntk does not coalesce: mouseDown/mouseUp, keyDown/keyUp, focus and blur, and the window manager's close request.

Motion and the wheel stay on the frame clock. mouseMove, and the hover enter/leave work it drives, are the opposite case — the pointer reports at device rate and only the newest position matters — so they coalesce to at most one repaint per frame. A scroll is the same case for a different reason: a touchpad reports one dozens of times a frame, and nobody can see those frames apart. What makes the wait free is that ntk coalesces a scroll by adding it up rather than keeping the newest, so a frame's event carries the whole distance and the pacing costs a paint, never a pixel.

Hover follows content. A scroll moves content under a pointer that did not move, and so can a layout that reflows it. After a frame that laid out — every frame of a scroll does — the window asks again what is under the pointer's last position, as a browser asks at the frame after a scroll: :hover, onMouseEnter and onMouseLeave change as a motion would change them, and the node under the pointer hears defaultMouseMove at that point, so an element that paints its own hover (a document, a graph) re-reads what it is over. onMouseMove is not called — the pointer did not move — and nothing changes while a press or a capture holds the pointer, or after the pointer has left the window.

Hover belongs to the active window, on macOS. Nothing in CSS or the DOM ties hover to focus — :hover is "while the user designates an element with a pointing device", and a mousemove is owed whenever the pointer moves over an element — but the platform does. A window there that is not the active one does not track the pointer: AppKit's own controls roll over in the key window alone, and a browser drops the moves over a window that is neither key nor main and tells the page the pointer left. So on the Cocoa backend a window that loses the keyboard hears onMouseLeave down its hover path, :hover comes off, an element that paints its own hover hears defaultMouseLeave, and no motion, enter, cursor or attention follows until the window is the active one again — when the hover comes back at the point the pointer is at, without waiting for it to move. <window onMouseOut> is not called: the pointer is still over it.

"Active" is the focus's answer, as it is for the caret (below): a window whose <Dialog> holds the keyboard still hovers. A <popup> nothing manages — a menu, a dropdown, a popover under a tray item — always does, since it is on the screen because the user asked for it, in an application that may have no active window at all. A press still lands where it was aimed, as the first click on a window always has here, and its gesture runs on; the wheel scrolls a background window as the platform has it. On X11, Wayland and Windows nothing changes: every toolkit there hovers in a window without the keyboard, and with focus-follows-mouse the question hardly arises.

Bursts of discrete input stay bounded by the same mechanism. While the server has not acknowledged the last frame, the response goes back to the paced path: click twice quickly and the first press paints immediately while the second folds into one catch-up frame. Update instantly, then catch up.

This needs ntk 5.2.0 or newer, which publishes the frameInFlight() gate the decision is made with. On an older ntk everything still works; the response simply waits for the next frame, as it did before.

When a handler throws

No error boundary can catch it. A boundary only sees throws React itself invoked, and a handler runs from an X event, so React is not on the stack. react-x11 therefore catches it at the dispatcher: the error is reported with the element, the handler name and the component that rendered the node, process.exitCode is set to 1 so the crash is still visible to CI and to a supervisor, and dispatch continues — one bad tooltip handler must not stop the handlers after it, or the frame loop.

react-x11: onClick on <box> in Panel threw. It ran from an X event rather
than a render, so no error boundary could catch it; dispatch continues.

onDrop is the one handler that may be async, and a promise it rejects with arrives here too — same message, same channel — rather than becoming an unhandled rejection, which node exits on. It also refuses the drop; see drag-and-drop.md.

createRoot({ onUncaughtError }) takes it over completely, which is the point of it being overridable: for a kiosk, crashing loudly is correct.

const root = await createRoot({
  onUncaughtError: (error, info) => {
    telemetry.report(error, info.componentStack);
    process.exit(1);
  },
});

Event object

{
  type, target, currentTarget,      // public instances
  x, y,                             // window coordinates
  localX, localY,                   // target-relative
  nativeEvent,                      // the raw ntk/X11 event
  shiftKey, ctrlKey,                // on every event, not just keys
  altKey, metaKey,                  // Mod1 and Mod4 — see Modifiers below
  preventDefault(), stopPropagation(),
  capturePointer(), releasePointer(),   // see Pointer capture below
  // mouse: button, detail (DOM-style click count: 2 = double, 3 = triple)
  // wheel: deltaX, deltaY (pixels), smooth
  // keyboard: keycode, keysym, group, codepoint, key, composing
  // composition: data
}

ev.screenX/screenY are where the pointer is on the virtual screen, in the same logical pixels ev.x/y are in — what to anchor a <popup> at, since <popup x y> are logical too. Undefined on an event with no pointer position.

nativeEvent.rootx/rooty is the same point in device pixels, which is the unit a node's abs is in — reach for it when doing geometry against abs, and for nothing else. The split is the same one ev.x and nativeEvent.x have (docs/scale.md).

detail counts a press as the next of a multi-click when it lands within the desktop's double-click time and distance of the last one (system.md), and the gap is the one between the times the two presses carry, nativeEvent.time, not between when each was handled. So a first click whose render outlasts the window still makes a double click with a second the user pressed in time. Presses that carry no time (win32's) are timed as they are handled.

On the Wayland backend a finger or a tablet tool drives the same mouse events, and those events alone carry nativeEvent.pointerType ('touch', 'pen', 'eraser' or 'mouse') with pressure, tiltX/tiltY, rotation, distance and tangentialPressure in the DOM's ranges; a mouse adds nothing, so a handler that never looks is unaffected. Every finger also arrives raw on the window as touchstart/touchmove/touchend/ touchcancel (wnd.on(...), not React props) — see wayland-backend.md.

x/y/localX/localY and the wheel deltas are logical pixels in the target's unit — the display scale, times any scale prop above it (scale.md). With no scale in the tree that is one unit for the whole window; with one, a handler on an unzoomed ancestor is reading the zoomed target's pixels, and ev.nativeEvent.x/y are the way back to the window's own.

A Ctrl chord is read from the keysym, not the code point. codepoint comes from the shifted keysym, so Ctrl+Shift+Z arrives as Z and Ctrl+Z as z; a handler that compares code points misses half of its own shortcut. ctrlChordLetter(ev) from react-x11/keysyms answers with the lowercase keysym either way — it is what <textinput> reads Ctrl+C/V/Z with, and it is exported because any widget with a chord of its own needs the same rule:

onKeyDown={(ev) => {
  if (ev.ctrlKey && ctrlChordLetter(ev) === keysymOf('d')) duplicateLine();
}}

That keeps working under a Cyrillic or Greek layout too: ev.keysym is the Latin keysym for the key however the layout is switched — see Layouts. For a chord an application would otherwise write out by hand, Accelerators is the shorter way: a menu item's shortcut already binds itself, and useAccelerator takes the same chord.

Modifiers

Four booleans, DOM names, on every event rather than only the keyboard ones — a shift+click, an Alt+drag and a Super+wheel all need them:

property	X11 modifier	usually
`shiftKey`	Shift	Shift
`ctrlKey`	Control	Ctrl
`altKey`	Mod1	Alt
`metaKey`	Mod4	Super

onKeyDown={(ev) => {
  if (ev.altKey && ev.keysym === keysymOf('b')) wordLeft();
}}

Mod1 is Alt and Mod4 is Super by convention, not by protocol. X says only that there are eight modifier rows and lets the keymap decide which keys sit in each; those two are where setxkbmap puts Alt and Super, and where every toolkit — GTK and Qt included — reads them from. The setup that disagrees still has the raw mask: ev.nativeEvent.buttons is the state field as it arrived, and MOD in react-x11/keysyms names its bits (MOD.Mod3, MOD.Lock for Caps Lock, and so on).

The primary modifier

On the Cocoa backend the editing chords are ⌘, not Ctrl. ⌘ arrives as metaKey (the DOM's own macOS mapping), and the app says which of the two its shortcuts are pressed with: app.primaryModifier is 'Super' there and absent everywhere else, X11 under XQuartz included. The built-in editors read it, so <textinput>'s Undo, Cut, Copy, Paste and Select All are ⌘Z, ⌘X, ⌘C, ⌘V and ⌘A on a Mac, Redo is ⇧⌘Z, and the right-click menu prints them that way. A ⌃ or ⌘ chord the field has no answer for is never typed as text — AppKit hands over the key's bare character with either held. A widget with chords of its own asks the same question with primaryModifierHeld:

import { ctrlChordLetter, keysymOf, primaryModifierHeld } from 'react-x11/keysyms';

onKeyDown={(ev) => {
  if (primaryModifierHeld(ev, app) && ctrlChordLetter(ev) === keysymOf('d'))
    duplicateLine();
}}

It is the same rule a menu bar's shortcut follows there, where Control means ⌘ (globalmenu.md), and the one accelerators follow: useAccelerator([['Control', 'K']]) is ⌘K on a Mac, and a drawn ContextMenu prints and answers ⌘S.

The editing keys follow it as well. Where shortcuts are ⌘, <textinput> and <textarea> move and delete the Mac's way — AppKit's own bindings, the table every Cocoa field reads — so a Mac user's hands already know them:

keys	does
⌥← ⌥→	a word back or forward
⌘← ⌘→, and ⌃← ⌃→	the start or end of the line
⌘↑ ⌘↓	the start or end of the value
⌥↑ ⌥↓	the start or end of the paragraph, and on to the next
↑ ↓ in a `<textinput>`	its start and its end, as in an NSTextField
⌥⌫ ⌥⌦	delete a word
⌘⌫	delete to the start of the line
⌃⌫	take the accent off the character before the caret — é to e
⌃A ⌃E	the start or end of the paragraph
⌃B ⌃F, ⌃P ⌃N	a character back or forward, a line up or down
⌃H ⌃D	delete a character back or forward
⌃K ⌃Y	kill to the end of the paragraph — its break, at its end — and yank it back

Shift extends the selection with every move. "Line" is the line as it is drawn, wrapped, and "paragraph" runs between line breaks; in a <textinput> both are the whole value.

Everywhere else the bindings are GTK's, Qt's and Windows': Ctrl+←/→ and Ctrl+⌫/⌦ by word, Ctrl+A to select all. The two sets disagree about Ctrl outright — ⌃← is the start of the line on a Mac, and ⌃A the start of the paragraph — so a backend has one set or the other, never a mix. Home and End move the caret to the ends of the line on every backend: AppKit scrolls without moving it, which a field — one line, its caret the point of the keystroke — has no use for.

⌃K's kill buffer is the application's and not the pasteboard, as it is in AppKit: a kill leaves what ⌘C copied alone, ⌃Y in one field yanks what ⌃K killed in another, and kills one after another add up, so the two that take a line and then its break yank back as the line. A sensitive field kills into nothing, for the reason it offers no Copy.

Any of them is the field's default action, so an onKeyDown that calls preventDefault() keeps the key, as it does every other.

Handlers

handler	notes
`onClick`	fires on the nearest common ancestor of press & release; `detail` counts multi-clicks
`onMouseDown` / `onMouseUp` / `onMouseMove`	move is coalesced to once per frame by ntk
`onMouseEnter` / `onMouseLeave`	do not propagate; synthesized by hover-path diffing, on motion and when a scroll moves content under a still pointer
`onWheel`	pixels, from the device or from X buttons 4–7; default action scrolls the nearest scroll container with somewhere to go
`onContextMenu`	right-click (button 3), after `onMouseDown`; default action opens the element's menu
`onKeyDown` / `onKeyUp`	delivered to the focused node (or the window); Space/Enter click an `onClick`, accelerators fire and Tab cycles focus, unless it took them
`onCompositionStart` / `onCompositionUpdate` / `onCompositionEnd`	text still being typed — a dead key, a Compose sequence; see below
`onFocus` / `onBlur`	focus follows mousedown (nearest `focusable` ancestor) and Tab traversal
`onDragEnter` / `onDragLeave`	do not propagate; drag-path diffing, the same shape as the hover pair above
`onDragOver` / `onDrop`	on a drop target; `onDrop` may be async — drag-and-drop.md
`onDragStart` / `onDrag` / `onDragEnd`	on a `draggable` node; the press is a click until it moves 4px

Space and Enter are a click

An onClick on a focusable node is operable from the keyboard, with nothing else written. Space or Enter on it dispatches the click — the whole press gesture, mousedown then mouseup then click, through the ordinary path — so a control hand-built out of a <box> behaves like a <Button>:

<box focusable role="option" aria-selected={on} onClick={() => open(channel)}>
  <text>{channel}</text>
</box>

The keys are a default action, which is the whole of the contract:

preventDefault() in the node's own onKeyDown takes the key back — that is how a widget that answers Enter with something other than its click (a disclosure opens a branch; the click only moves the selection) keeps it;
a node with no onClick is untouched, whatever its role says. A role advertises an action to an assistive technology, which has no other way to ask; a key press is already at the node, so there is nothing to advertise and nothing to activate. role="button" with only an onKeyDown stays yours;
<textinput> and <textarea> never activate: their own defaultKeyDown answers the keystroke, so Space types a space;
a scroll pane keeps Space. Space and Shift+Space page a scrolling <box> (elements.md) — that is a default action too, and the pane answers it before this one, so a clickable pane pages with Space and activates with Enter. A focusable row inside a pane is not affected either way: default actions run on the focused node, and the pane is not it;
a chord is not a press. With Ctrl, Alt or Super held — ⌘ or ⌃ or ⌥ on the Cocoa backend — Space and Enter are a command, and the node leaves them to whoever bound it: a menu's Ctrl+Return fires with focus on a clickable box exactly as it does anywhere else (accelerators).

Shift is not a command, and it travels: the synthesized click carries the key press's own modifier mask, so Shift+Enter reaches onClick as a shift-click.

It is the same function an assistive technology's activation goes through, on purpose — one definition of "activate" for the pointer, the keyboard and Orca, which cannot then disagree about a control (accessibility.md).

Accelerators

A menu's shortcut is a binding. MenuBar and ContextMenu answer their own items' chords while they are mounted, so the array that draws the menu is the array that binds it:

<MenuBar
  menus={[
    {
      label: 'File',
      items: [
        { label: 'Save', shortcut: [['Control', 'S']], onSelect: save },
        {
          label: 'Save As…',
          shortcut: [['Control', 'Shift', 'S']],
          onSelect: saveAs,
        },
      ],
    },
  ]}
/>

Ctrl+S calls save() without the menu being opened. The same array is what aria-keyshortcuts announces and what crosses the bus when the desktop's panel draws the menu (globalmenu.md) — and it stays bound in that case, because the panel draws the rows but the key is pressed in your window and nothing else is going to deliver it. (The macOS menu bar is the exception, and answers the ⌘ chords it shows by itself — below.)

For a shortcut that is not in a menu — there are always some — useAccelerator takes the same chords, so one can be moved into or out of a menu without being rewritten:

import { useAccelerator } from 'react-x11';

useAccelerator([['Control', 'K']], () => openPalette());

The chord

[['Control', 'S'], ['F2']] is dbusmenu's aas: a list of alternatives, each a list of modifier tokens — Control, Alt, Shift, Super — ending in the key. Any alternative fires; only the first is drawn, since a row has one shortcut column.

The key is named the way X names it, which is what gdk_keyval_name() emits and what a panel's importer parses: plus rather than +, Prior rather than PgUp, Return rather than Enter. A one-character name is that character. keysymFromName() in react-x11/keysyms is the resolver, and matchesShortcut(ev, shortcut, { primary }) the matcher, for an application dispatching chords its own way.

Control is the app's primary modifier: Ctrl, except on the Cocoa backend, where it is ⌘ — the key a Mac user saves with, the key a drawn row prints (⌘S, ⇧⌘Z) and the key the binding answers (The primary modifier). Super is ⌘ there too, so a chord cannot ask for ⌃ on a Mac; a chord is matched with it up. The menus and useAccelerator read the app's answer themselves, and matchesShortcut takes it as an option, since it is a pure function with no app to ask:

import { matchesShortcut } from 'react-x11';
import { primaryModifier } from 'react-x11/keysyms';

matchesShortcut(ev, [['Control', 'S']], { primary: primaryModifier(app) });

Four rules, all of which a hand-rolled onKeyDown gets subtly differently:

exact on the four modifiers. Ctrl+S does not fire on Ctrl+Shift+S.
indifferent to the locks. Caps Lock and Num Lock are not modifiers here — ctrlKey/altKey/shiftKey/metaKey are the four named bits and nothing else, so a chord keeps working with either light on.
the key, not the character. Matching is against ev.keysym, the Latin keysym for the physical key, so a chord survives a layout switch (Layouts) — and ['Control', 's'] and ['Control', 'S'] are one binding rather than two. A chord that names a symbol also matches the character the key produced, because + is the shifted = and [['Control', 'plus']] has to be pressable; letters stay out of that path, since it is exactly what would make Ctrl+Shift+S fire a Ctrl+S binding.
enabled and visible gate it. A dimmed item's chord fires nothing, and neither does an item inside a submenu whose parent is disabled — a command you cannot reach by opening the menu is not one a key should reach.
Control is the primary modifier, above — exact on it as on the rest, so ⌃⌘S does not fire a ⌘S binding either.

Who gets the key first

Accelerators sit at the end of the same default-action chain Tab and Space/Enter are in, and preventDefault() is the word at every step:

the application's own onKeyDown, capture then bubble;
composition — a dead key, a Compose sequence;
the focused element's own behaviour (<textinput> editing, a scroll pane's page keys);
accelerators;
focus traversal, for Tab.

So a focused text field keeps the chords it answers: Ctrl+C copies the selection and never reaches a menu item that also says Ctrl+C. Ctrl+S is not one of the field's, so it falls through to the menu — a control that swallowed every chord would be a control no application could put a shortcut behind.

Return is the same rule. A <textinput> answers Return and Shift+Return with onSubmit, and nothing else: Ctrl+Return, Alt+Return and Super+Return — ⌘↩ on the Cocoa backend — are chords, and reach the menu that prints them. A field with no onSubmit has no answer for Return at all, so the key goes on to whatever binds it, a form's [['Return']] default button included. A <textarea> keeps Return and Shift+Return for the newline and Ctrl+Return (⌘↩) for onSubmit when it has one; Alt and Super on Return are chords there too, except on the Cocoa backend, where ⌃↩ and ⌥↩ are AppKit's newline.

Two things suppress them entirely, both because something else has the keyboard:

an open menu. It is holding a pointer grab, and a chord firing a second command out from under the one being pointed at is a bug nobody reproduces.
a modal <popup> (trapFocus, which is what Dialog sets). Ctrl+S while a confirmation is up saves nothing. A menu declared inside the modal still works — the containment rule is the one Tab traversal already follows — and useAccelerator's scope option is how a hook-registered shortcut joins it:
```
const inDialog = useRef(null);
useAccelerator([['Control', 'Return']], confirm, { scope: inDialog });
```

A chord belongs to the window whose menu declared it, so a second top-level window does not answer it, and enabled: false unbinds one without unmounting anything. accelerators={false} on a MenuBar or ContextMenu turns the whole of this off for an application that already has a dispatcher.

An app with no <window> at all — a menu-bar app, whose whole UI is the popover a tray click opens — binds against the root-level <popup> that took the keyboard instead (elements.md). There is nothing else for a shortcut to belong to, and it is the window the keys are arriving on. A binding that lands on nothing at all — no window and no popup either — warns once in development and names scope, rather than leaving a chord that is drawn, announced and dead.

On the Cocoa backend a MenuBar is drawn by the system (globalmenu.md), which installs each item's chord as an NSMenu key equivalent where it can spell one — a single chord on a character key — and AppKit then runs the item on a ⌘ chord by itself. It does so after the window has seen the key, whatever the window did with it. So those chords are reserved: the window's accelerators are not offered them at all, neither the bar's own binding nor a useAccelerator on the same chord, whichever mounted last, and the item runs once. A chord the menu bar cannot spell — a function key, a second alternative, plus — or one with no Control or Super in it stays the window's, and fires the way it does anywhere else.

The reservation cannot reach steps 1 and 3 above, which run before it: an onKeyDown that answers ⌘S for itself, or a focused field answering ⌘C beside an Edit menu whose Copy says ⌘C, runs alongside the menu item rather than instead of it — preventDefault() there does not reach AppKit. Leave a chord the menu bar shows to the menu bar.

The wheel

ev.deltaX / ev.deltaY are pixels, positive down and right, and one notch of a wheel is 48 of them — the step an arrow key takes, so the two input routes move a list by the same amount.

Where the server has XI2, those pixels are the distance the device actually measured. The core protocol has no wheel at all: a scroll arrives as a click of button 4/5/6/7, and a click carries no magnitude, which is why every scroll used to be exactly one notch. XI2 carries the same gesture as the device's own scroll valuators, so a touchpad's two-finger scroll reports the fractions of a notch it really was, and deltaY is 14.5 rather than 48 twice a second.

<box
  style={{ overflow: 'scroll' }}
  onWheel={(ev) => {
    ev.deltaY; // pixels — fractional from a touchpad
    ev.smooth; // whether the device can report a fraction at all
  }}
/>

ev.smooth says which kind of device this was, not whether this particular delta happened to be fractional: true means the valuators are flowing and the next event may be a third of a notch, false means the emulated button, which can only ever say one. It is the flag to branch on for anything that wants to animate a scroll — a whole notch is worth easing towards, a stream of measured pixels is not.

Nothing is opted into. A <window> selects XI2 the first time it is scrolled and falls back to the wheel buttons where the server has none, so a handler written against deltaY works on both and the difference is the value. A <popup> is on the buttons deliberately — it holds a pointer grab, and a core grab delivers core events — so a scroll inside an open menu moves a notch at a time. Needs ntk >= 7.5.0.

The selection waits for the first wheel because it is not free. An XI2 selection replaces the core one for the same event type, and an XIMotion is around 136 bytes on the wire where a core MotionNotify is 32 — measured against Xorg 21.1. Motion is the one event that keeps arriving at frame rate for as long as the pointer is over the window, so selecting it up front bills every window about 8 KB/s of pointer traffic while the pointer crosses it, including the dialogs, toolbars and forms that never see a wheel at all.

What waiting costs is the opening event of the first gesture in a window's life, and it costs less than it sounds: a mouse wheel reports whole notches either way, and ntk treats the first valuator event as a seed with no distance to report, so under an eager selection that same first event moves nothing at all.

<window xi2> selects at creation anyway, for an app whose whole interaction is a touchpad and which wants the very first flick smooth. <window xi2={false}> refuses the selection for the window's whole life.

Shift turns a vertical scroll sideways for a device with only one axis (the convention every toolkit follows); a device that reports its own horizontal axis keeps what it reported. The default action is the hit node's own defaultWheel and then the scroll chain — see extending.md for the element whose wheel is a zoom rather than a scroll, and extending.md for how anything joins the chain.

Composition: dead keys and Compose

é is not a key. On a French, German or us-intl layout it is dead_acute then e, and a dead key is a keysym with no code point at all — so a renderer that types from ev.codepoint types the letter and drops the accent. That is most accented input in Europe, and it is invisible to anyone testing on a US layout (issue #272).

A composition is text the user is still typing. It shows at the caret, underlined, and it is not the value until it commits:

dead_acute        →  the field shows ´ (underlined). value unchanged.
e                 →  the field shows é. value is now …é, one undo step.

Everything about it is on by default and needs no configuration:

you press	you get
`dead_acute` `e`	`é` — and any base letter, in any script
`dead_circumflex` `dead_acute` `e`	`ế` — dead keys stack
`dead_acute` space	`´` — the accent on its own
`dead_acute` `q`	`´q` — no such character, so nothing is swallowed
Compose `o` `c`	`©`
Compose `'` `e` (or `e` `'`)	`é`
Compose `-` `-` `-`	`—`
Escape mid-sequence	nothing typed, and the accent goes away

The dead keys are Unicode's own composition rather than a table somebody maintains, so dead_breve + и is й and dead_acute + α is ά without anyone having written those down. What is written down is the part Unicode has no rule for: dead_stroke + o is ø, and the Multi_key symbol sequences, which are conventions rather than compositions.

Handling it yourself

The three events mirror the DOM's. data is empty on the start, the text showing at the caret on each update, and the committed text at the end — empty when the sequence was abandoned.

<textinput
  onCompositionUpdate={(ev) => setStatus(`composing ${ev.data}`)}
  onCompositionEnd={(ev) => setStatus('')}
/>

A key an open composition took carries no text of its own. ev.key and ev.codepoint are undefined on it and ev.composing is true, because its text arrives on the composition event instead — an application that types from onKeyDown would otherwise insert o, c and then ©. The keysym is still there, so a chord still matches.

The order is application chords → composition → the element → focus traversal: an onKeyDown that calls preventDefault() keeps its key and the composer never sees it, and a key the composer does take never reaches the element's defaultKeyDown — so a dead key cannot also fire an accelerator, and a Compose sequence containing z cannot undo halfway through.

A composition is abandoned, never half-committed, when focus leaves, when the window loses the keyboard, or when a press puts the caret somewhere else.

A screen reader is told the same story: the preedit is a text run of its own and its churn is marked as text the user did not type, so the accent is not read out and the character it commits is — accessibility.md.

Input methods

On the Wayland backend the compositor's input method (IBus under GNOME) drives the same three events over zwp_text_input_v3: its preedit arrives on onCompositionUpdate and the text it commits on onCompositionEnd, inserted the way a typed character is. Two things are only there:

ev.cursorBegin / ev.cursorEnd on an update — code-point offsets into data — when the engine says where inside its preedit the cursor is, or which segment of a phrase it is converting (drawn with a heavier underline). A dead key never sets them.
a commit with no preedit before it — an emoji picker, an engine that commits directly — is a start and an end in one.

Keys the input method consumes never reach the application, so a dead key composed by IBus does not also reach the client-side table; a key that does arrive is one the input method declined. <textinput sensitive> offers the input method none of its text, and inputMode on a <textinput> tells it what to expect (elements.md).

The Cocoa backend has no input method yet — NSTextInputClient is macos.md's IME work — so its text is what each key event says it typed. A dead key such as ⌥E types nothing and shows nothing, and the key after it types what macOS put on that key: é where the event carries the dead key's composition, the bare letter where it does not, never the two letters reading the key's own character used to type. A key that typed more than one character — the accent and a letter it does not combine with, ´s — commits them as one composition, a start and an end in one, the way an input method's commit arrives. Press-and-Hold accents and CJK input wait on the same work.

Changing the table

import { XK_MULTI_KEY } from 'react-x11/keysyms';

const root = await createRoot({
  compose: {
    // this machine's Compose file, which is how a personal ~/.XCompose is
    // picked up — usually absent on macOS, where nothing is lost
    file: 'system',
    sequences: [[[XK_MULTI_KEY, 'l', 'd'], '🦆']],
  },
});

compose: 'system' is the whole file shorthand, compose: false turns composition off for an app that does its own, and later definitions win over earlier ones — which is what makes a Compose file an override of the built-ins rather than an addition beside them. Parsing is X's own format; include directives are ignored, and a line naming keysyms outside ASCII and the dead-key block (<Greek_alpha>, <Cyrillic_a>) is skipped rather than guessed at.

What this is not is an input method. There is no preedit arriving from another process and no candidate list, so CJK still needs XIM or an IBus/Fcitx client — issue #272 tracks it. The events above are the surface it will arrive on.

Layouts

A key event answers two questions and, the moment a non-Latin layout is active, it has to answer them differently:

what the key typed — ev.key and ev.codepoint, the active layout, the active level. A Cyrillic layout types Cyrillic.
what the key is called — ev.keysym, the Latin keysym for that key, whichever group holds it. Shortcuts do not move with the layout, in GTK, in Qt and in the browsers, and Ctrl+Z has to keep undoing while the user is typing Russian.

So ctrlChordLetter(ev) === keysymOf('z') matches the physical Z key under every layout, and nothing in a widget has to know that a layout exists.

⌥ types, on the Cocoa backend. It is the layout's third and fourth level there rather than a modifier: ⌥S is ß on a US keyboard, and on a German one ⌥L is @ and ⌥5 and ⌥8 are [ and { — the only keys that type them. So ev.key and ev.codepoint are what the layout typed, with ⌥, Shift and Caps Lock applied, while ev.keysym is still the key (s) and ev.altKey is true: an Alt+S accelerator still matches, and a field types ß. A ⌘ or ⌃ chord types nothing and is named by its key, so ⌘⌥S is a chord on S — the same split the DOM makes on a Mac. ev.group is the active XKB group, 0-3, for an application that wants to show which layout is live — a switch sends no other notice.

Where the Latin keysym comes from depends on how the layout got there, and the two mechanisms have nothing in common:

Linux/XKB loads every layout at once as a group and switches which one is live; the keymap never changes and no MappingNotify is sent. The Latin keysym is on the same keycode, in whichever group is the Latin one — which under ru,us is the second.
XQuartz has no groups. It synthesizes the keymap from the active macOS layout and overwrites it when the input menu changes (Preferences → Input → "Follow system keyboard layout"; without that, nothing downstream can help), then sends MappingNotify. After a switch to Russian no group anywhere holds Latin, and the only thing left that still means "the Z key" is the keycode — so that is what is used, against the US position of whichever keycode scheme the server speaks.

const root = await createRoot({
  // 'latin' is the default; 'layout' reports the keysym the layout put on
  // the key, for an app matching shortcuts its own way
  accelerators: 'layout',
});

accelerators also takes a keycode→keysym table ({ 52: 'z' }) for a server whose keycodes are neither evdev's nor macOS's, which is the only case the two built-in ones do not cover.

One thing the core protocol cannot express is the difference between two groups of two levels and one group of four, so the AltGr row is not reachable: ev.keysym and ev.codepoint read groups only. Resolving it needs XkbGetMap, which node-x11 does not implement.

Pointer capture

ev.capturePointer() routes every following mousemove and mouseup to the capturing node instead of whatever is under the pointer, so a drag keeps working past the widget's own bounds — and a release far outside it still ends the gesture. This is what Slider is built on:

onMouseDown: (ev) => {
  ev.capturePointer();
  setDragging(true);
},
onMouseMove: (ev) => { if (dragging) setValue(valueAt(ev)); },
onMouseUp: () => setDragging(false),

Capture is released automatically on mouseup (like the DOM's implicit pointer capture) and when the capturing node unmounts; ev.releasePointer() ends it early. While captured, hover stays where it was — dragging must not light up every widget the pointer crosses.

Focus

focusable opts a node into focus (<textinput> is focusable by default, and so is a scroll container with somewhere to scroll), autoFocus takes it at mount, and every drawn node has focus() / blur() / focused on its ref — plus focusWithin, which is true while focus is on the node or inside it, the question a modal asks before taking focus itself. To draw that rather than read it, there is a ':focus-within' style block (styling.md), which is what a row containing a field wants. focus() hands the node back, so a component can forward it straight out of an imperative handle. Focusing a node inside a scroll container scrolls it into view — unless a press focused it, since the node is under the pointer. Mousedown focuses the nearest focusable ancestor of the hit node; Tab / Shift+Tab cycle through focusable nodes in tree order. Keyboard events route to the focused node's ancestor chain. disabled opts a node back out of focus, whatever else it says.

A focused node shows a ring, and how focus arrived decides whether it does. A press sets :focus; everything else — Tab, autoFocus, node.focus(), a modal handing focus back as it closes — also sets :focus-visible, and that is the state the ring is drawn on. A press on a text control is the one press that sets both, because a field the keyboard is about to go to has to say so however focus got there. It costs no layout and needs no opt-in; see styling.md for restyling it.

Tab order

tabIndex sets the sequential focus order, following the DOM's rules:

nodes with a positive tabIndex come first, in ascending order;
then everything focusable without one (the implicit 0 group), in tree order;
tabIndex={-1} is focusable — by a press, and by focus() — but Tab never lands on it;
an explicit tabIndex makes a node focusable without also passing focusable.

Tab out of a node that is not in the tab order (tabIndex={-1}, or a node outside the current focus scope) and traversal starts from the beginning of the order.

<box tabIndex={1} />   {/* visited first  */}
<box tabIndex={2} />   {/* then this      */}
<box focusable />      {/* then tree order */}
<box tabIndex={-1} />  {/* clickable, never tabbed to */}

Traversal is a default action like any other, and it runs last: an onKeyDown that calls preventDefault() on Tab keeps it, and so does an element whose own defaultKeyDown consumes it — an editor indenting with Tab. An element that does owes the keyboard user a way out of it, which is the Escape-arms-one-Tab convention in extending.md.

Focus scopes (modals)

trapFocus makes a node own a focus scope. While it is the innermost scope:

Tab / Shift+Tab only visit focusables inside it — the rest of the window is unreachable by keyboard;
a press outside it does not move focus (poking at the window behind a modal is inert as far as focus goes — the press itself still dispatches, so pair it with grab + onDismiss for a real modal);
when the scope unmounts, focus goes back to whatever had it before the scope opened — no bookkeeping in the widget.

That is a modal dialog, with the popup taking focus at mount:

function Dialog({ open, x, y, onClose }) {
  if (!open) return null;
  return (
    <popup
      trapFocus
      grab
      x={x}
      y={y}
      width={280}
      height={120}
      onDismiss={onClose}
    >
      <textinput autoFocus />
      <Button label="OK" onPress={onClose} />
    </popup>
  );
}

Scopes nest (a modal opened from a modal); the innermost one wins, and popping it hands focus back to the outer one. Programmatic focus() is never blocked by a scope — the trap is about Tab and presses.

Focus inside a `<popup>`

An override-redirect window never receives the X input focus, so a popup cannot hold focus itself: the owner window does, and a node inside the popup can be the focused node of that window. Keys arrive at the owner window and are dispatched to it, then bubble out through the popup's position in the JSX tree into the owner's handlers, so nothing has to proxy them.

One consequence worth knowing: a press inside a popup that lands on nothing focusable leaves the owner window's focus alone. Menus depend on it — their rows are not focusable, and the trigger keeps handling keys while the menu is open (Menu, Select).

A popup with no owner window — a popover a tray click opened, in an app with no window of its own — has nowhere for its keys to arrive, and takes them itself with grabKeyboard (elements.md).

Window focus

Node focus is per <window>, and the window itself may or may not be the one the X server sends keys to — that is the window manager's call. <window onFocus> / <window onBlur> report it (ntk ≥ 3.7.0, X FocusIn/FocusOut).

While the window is unfocused the focused node keeps focus, exactly as document.activeElement survives a window blur in a browser — it just stops looking active: a <textinput> caret stops blinking, and resumes when the window is focused again. Calling focus() on a node in a window that does not have the input focus asks for it (X SetInputFocus), though a window manager is free to refuse.

Which of an application's windows a key is delivered to is a separate question again, and not one the application answers: the server sends it to the window holding the input focus, or to whichever descendant of that window the pointer happens to be over. A nested <window> and a <popup> put the two apart — the field is focused inside them, the keyboard belongs to the top-level — so a key is dispatched to the node that has focus, whichever of that top-level's windows it arrived at, and bubbles from there out through the JSX tree. Where more than one window holds a focused node, the one focused last is where the user is typing and the one that answers.

"Unfocused" is likewise the focus's answer rather than any one window's. A <popup> shares its owner's focus, and a managed one — a <Dialog> — is a real window the window manager focuses in its own right, so opening one takes the X focus off the owner at the moment the field inside the dialog starts receiving keys. The caret follows the window that actually holds the keyboard, whichever of the ones sharing that focus it is; asking the owner alone is how a focused field ends up with a :focus ring and no caret. By the same token, focus() on a node inside an open dialog does not ask the server for the input focus — the dialog already has it.

Focus and visibility

Focus follows visibility. A subtree that goes off the screen gives up the keyboard: a <Suspense> boundary showing its fallback, an <Activity mode="hidden">, a display: 'none', a <popup> being unmapped. The focused node fires onBlur, :focus/:focus-within come off, and keys go to the window instead — because a control nobody can see must not be collecting keystrokes, and the application's state must not advance from them. Tab skips invisible nodes for the same reason.

And it comes back with it. When the subtree is revealed, focus returns to where it was, ring and all, so a boundary that re-suspended mid-edit leaves the user typing where they were. Two rules keep that from being focus stealing:

it only happens when nothing else has the keyboard — anything focused while the subtree was away keeps focus;
it is a restore rather than a navigation: no scrolling into view, and no X SetInputFocus, so a background window revealing something never takes the keyboard off another application.

createRoot({ restoreFocusOnReveal: false }) turns the second half off, for an app that wants the browser's answer — focus that fell to nothing stays there, and coming back is the user's own Tab. The release is not optional.

Cursors

The cursor style property ('pointer', 'text', 'wait', 'move', 'crosshair', 'ew-resize', 'ns-resize', 'grab', 'not-allowed', …) applies the deepest hovered node's cursor to the window, via ntk's cursor cache over the standard X cursor font.

cursor: 'none' hides the pointer (ntk ≥ 4.2.0) — the kiosk case. It is the one name that is not a glyph in that font, so ntk builds it from an empty 1×1 mask. Note it is not the same as setting no cursor at all: with none of a node's ancestors naming one, the window inherits the root window's cursor and the pointer stays visible.

Drag and drop

Drag and drop rides this event system — same hit testing, same capture/bubble dispatch, same style states — so the props sit alongside the pointer handlers on any drawn element, <window> or <popup>:

<box
  dropAccept={['files']}
  onDrop={(e) => setPaths(e.files.map((f) => f.path))}
  style={{ ':drag-over': { borderColor: '$accent' } }}
/>

handler	notes
`onDragEnter` / `onDragLeave`	do not propagate — path diffing, like hover; paired with the `':drag-over'` state
`onDragOver`	per pointer position; `e.accept(action)` / `e.reject()` answer the source
`onDrop`	may be async — the protocol reply waits for the returned promise, bounded by a watchdog
`onDragStart` / `onDrag` / `onDragEnd`	the source side of a `draggable` node; `':dragging'` styles it for the duration

Two things that differ from the events above. A press on a draggable node is still a click until the pointer moves 4px, and a completed drag suppresses the click that would otherwise follow — the same bargain the DOM makes. And a drag that leaves the app's own windows keeps working: it is promoted to the X11 XDND protocol and can be dropped into a file manager, an editor or another react-x11 process, with the handlers unchanged.

The full reference is drag-and-drop.md: the dropAccept matching rules, the event payload (e.files, e.text, e.getData, e.items), dragData and lazy payloads, the useDropTarget and useDragSource hooks, drag previews, interoperating with GTK and Firefox, and how to drive a drag in a test.

Dispatch​

When the response is painted​

When a handler throws​

Event object​

Modifiers​

The primary modifier​

Handlers​

Space and Enter are a click​

Accelerators​

The chord​

Who gets the key first​

The macOS menu bar​

The wheel​

Composition: dead keys and Compose​

Handling it yourself​

Input methods​

Changing the table​

Layouts​

Pointer capture​

Focus​

Tab order​

Focus scopes (modals)​

Focus inside a <popup>​

Window focus​

Focus and visibility​

Cursors​

Drag and drop​