The machine around the app

Six hooks for the things an application has to read off the system rather than work out for itself: the monitors, what the window manager did with the window, whether anyone is at the desk, the state of the keyboard, how the desktop wants an app to feel, and the language it was launched in — and a store for what the app remembers itself, between launches.

import {
  useScreens,
  useWindowState,
  useIdle,
  useKeepAwake,
  useKeyboardState,
  useDesktopSettings,
  createSettings,
  useLocale,
} from 'react-x11';

They share a shape, and it is worth knowing before reading any one of them:

Nothing is asked of the server until a component asks. Every one of these costs round trips or an event selection, and an app that never calls them pays for none of it.
Every one has an answer with no extension present. X is a protocol with thirty years of optional pieces, and "this display cannot say" is a real state rather than an error. Each hook below names what it reports then, and which field tells that apart from a genuine "no".
The colours are somewhere else. Light or dark, the accent and reduced motion are system appearance, which has a ladder of its own.

`useScreens()` — the monitors

const { screens, primary, workArea, virtual, source } = useScreens();

<Select
  value={monitor}
  onChange={setMonitor}
  options={screens.map((s) => ({
    value: s.name,
    label: `${s.name} — ${s.width}×${s.height}`,
  }))}
/>;

Each entry in screens:


`name`	`'HDMI-1'`, `'eDP-1'` — null where the server has no RandR
`x` `y` `width` `height`	the rect in virtual-screen coordinates
`available`	that rect minus the panels
`primary`	the desktop's main monitor
`widthMM` `heightMM`	physical size, or null
`refreshRate`	Hz to two decimals (`59.99`), or null
`rotation`	`0`, `90`, `180` or `270`
`outputs`	every output on this monitor — two names means it is mirrored
`scale`	this monitor's device pixels per logical pixel

Re-renders when a monitor is plugged in or unplugged, when the arrangement changes, and when a panel appears, moves or auto-hides.

The rects are in logical pixels, like every other length an app touches, and scale is the per-monitor answer the display-scale ladder arrived at — a retina lid and an office monitor genuinely differ. The root's own scale is the primary monitor's; see scale.md.

The names arrive after the geometry

source says which tier answered. The geometry resolves during createRoot() from Xinerama, which is one round trip; the names, the primary flag and the physical sizes take a RandR walk — GetScreenResourcesCurrent, then a GetOutputInfo and a GetCrtcInfo per output, ten or more round trips on an ordinary two-head desktop — and that deliberately does not hold startup up.

So a component can render once with source: 'xinerama' and null names, and again a moment later with source: 'randr' and real ones. The rects do not move between the two: Xinerama on any modern server is RandR's emulation of it, so what arrives late is added rather than corrected. Where a name is what gets persisted — "reopen on the monitor I was on" — treat null as not known yet and keep the last one rather than writing it.

'screen' is the tier under both: one entry covering the whole display, for a server with neither extension. null is a headless mock with no display at all.

`available` is an approximation on X11, and the only one here

_NET_WORKAREA — the desktop minus the docks and panels that reserved space — is published for the whole virtual desktop, not per monitor. That is an EWMH weakness rather than a choice made here. So it is applied as a per-axis bound on top of the monitor rect: exact on one head, and on several it still takes a top or bottom panel off the height without pretending to know which head the panel is on.

A true per-monitor work area means reading _NET_WM_STRUT_PARTIAL off every window on the screen and intersecting the reservations that land on each head — a full window-tree walk, redone whenever any panel changes. If you need that, useApp().X is the escape hatch.

On Wayland

The same shape, from wl_output (wayland-backend.md): name is the compositor's connector name (DP-1, eDP-1) and arrives with the geometry rather than after it; the rects are xdg_output's logical ones. The protocol has no primary — the entry at the origin is flagged — and no work area: available is each monitor's own rect, less what the compositor told a window on it to fit in (xdg_toplevel.configure_bounds, the monitor minus its panels), so it is exact per monitor, as on macOS, once a window has appeared there. scale is the monitor's own, the fraction under fractional scaling. source reads 'test' on both native backends — the stamp of the seam they publish through.

On macOS it is exact. NSScreen.visibleFrame is per screen already — that display's own menu bar and Dock taken off — so each monitor carries its real usable rect and no approximation runs. workArea there is still one rect, because the field is one rect by definition; it is the primary screen's, and on a multi-display Mac screens[n].available is the answer to prefer. primary is the screen with the menu bar, refreshRate the panel's own rate, and name is null — the bridge does not report one.

On macOS the layout is asked for, not announced

Every other backend is told: RandR sends an event, a wl_output announces itself. macOS has no such event for a client — the bridge keeps its NSScreen copy current on the system's own notification and says nothing — so react-x11 re-reads the layout instead, at the moments it matters:

before a placement, which is where a stale rect would be visible — a popup flipped and clamped into a monitor that has moved, an auto-sized window capped by one that is gone;
when a window reports that it moved, at most once a second, because a display arriving or leaving moves the windows that were on it;
on a clock while a useScreens() subscriber is mounted, every createRoot({ cocoa: { screenPoll } }) ms — 500 by default, 0 for never. An app that never calls useScreens() never polls.

So a component watching the layout sees a monitor plugged in about half a second later than an X11 one does, and everything else sees it at the moment it asks. useApp().refreshScreens() publishes the layout right now for an app that knows before any of those.

Mirroring

Two outputs showing the same pixels share one CRTC and are reported as one monitor, with both names in outputs. A laptop mirroring to a projector is one screen to put a window on, and screens.length === 2 there would be a wrong answer an app would act on.

`useWindowState()` — what the window manager did

const { focused, visible, fullscreen } = useWindowState();

// a title bar that dims when the window is not the active one
<text style={{ color: focused ? theme.text : theme.textMuted }}>{title}</text>;

// and work that is pointless while nobody can see it
useEffect(() => {
  if (!visible) return;
  const id = setInterval(poll, 1000);
  return () => clearInterval(id);
}, [visible]);


`focused`	this window has the keyboard
`visible`	the one to branch on — not minimized, not covered, still drawing
`minimized`	`_NET_WM_STATE_HIDDEN`: iconified, or shaded away
`maximized`	both axes; one axis alone shows up in `states`
`fullscreen`	what the WM actually did, not what `<window fullscreen>` asked for
`obscured`	fully covered — always false under a compositor
`presenting`	the display is still scheduling frames — Wayland; true everywhere else
`states`	the raw `_NET_WM_STATE` names
`desktop`	the workspace index, or null

<window states> is what a window asks for; this is what it got. The two part company routinely — a user hits a maximize hotkey, a tiling WM declines a fullscreen request — and an app that mirrors the state in its own UI has nowhere else to read it.

On the Cocoa backend the same rows come from AppKit, in the same _NET_WM_STATE names (@windowkit/appkit 0.30.0): fullscreen is the title bar's green button, or <window fullscreen>, maximized the zoom (maximized_vert and maximized_horz together), minimized the Dock (hidden), and states lists focused for the key window. fullscreen turns as AppKit's transition begins, before the animation, so a toolbar an app hides in full screen goes while the window grows rather than after it:

const { fullscreen } = useWindowState();
return fullscreen ? <Page /> : [<Toolbar />, <Page />];

obscured and desktop keep their initial values there — a Space is not a numbered workspace — and on a bridge older than 0.30.0 only focused moves.

With no argument it reads the window the component is in, inferred the way useTopLevelWindow() infers it: exact for a one-window app, and a documented guess for a tree with several. Pass a ref to be certain.

const win = useRef(null);
const { fullscreen } = useWindowState(win);
return <window ref={win}>…</window>;

The first render answers focused: true, visible: true rather than waiting for a round trip. A window opens focused and on screen far more often than not, and a title bar that renders dimmed on frame one and un-dims on frame two is a flash on every launch.

`obscured` and the compositor

A composited window is never obscured. The compositor redirects it to an offscreen pixmap, so the server considers it entirely visible whatever is stacked on top, and VisibilityNotify says so. One is running on every stock GNOME and KDE session. That is X working as designed and there is no protocol answer to it.

So obscured is a bare-WM optimisation, and visible — which folds in minimized, the signal that does survive compositing — is the field to branch on. An animation paused on visible stops when the window is minimized everywhere, and additionally when it is buried on a desktop with no compositor.

`presenting`, and the Wayland frame clock

A Wayland compositor will not tell you a surface is covered either — but it stops sending it frame callbacks, and on that backend a frame callback is the only thing that paces the frame loop. So a window nobody is showing draws once and then stops, while React above it goes on re-rendering into a tree that reaches no screen. That is the compositor being right (painting into a surface nobody sees is work for nothing) and it used to be invisible: no error, no warning, and nothing an app could ask.

presenting is that state, published. It goes false after a couple of seconds of silence with a repaint waiting, and true again on the very next frame callback — the compositor still holds the one we asked for, and answers it the moment the surface is shown again. It folds into visible, so an animation already paused on visible pauses here too:

const { visible, presenting } = useWindowState();

// nothing this draws would reach the screen; stop simulating as well
useEffect(() => {
  if (!visible) return;
  const id = setInterval(step, 16);
  return () => clearInterval(id);
}, [visible]);

// and the reason, where a status line would rather say it than go blank
const status = presenting ? 'live' : 'paused — this window is not on screen';

It is a signal to stop work on, not a frame-accurate one: two seconds of silence is what makes it certain, so nothing that has to be exact should read it. On X11, macOS and the headless mock it is true and stays there — their frame clocks do not depend on a compositor's goodwill, and obscured is the question to ask there instead. The backend also says it once on stderr in development, because "the app is alive and has drawn once" is otherwise an unguessable state; see wayland-backend.md.

`useIdle()` and `useKeepAwake()` — is anyone there

const away = useIdle(5 * 60_000);
<Avatar status={away ? 'away' : 'online'} />;

Idleness is the whole display's, not this window's: it counts input on every device, whichever application it went to. That is the right meaning for a presence indicator, an auto-save, or a dashboard that stops refreshing when the desk is empty — and the wrong one for "has the user ignored my window", which is useWindowState().focused.

Where the X server carries an IDLETIME counter — Xorg does — this costs no timer at all: a SYNC alarm fires when the counter crosses timeout and another when input pulls it back down, which is what every idle daemon on the desktop is built on. On a server without one (XQuartz) it falls back to polling MIT-SCREEN-SAVER, scheduled against the remaining time rather than on a tick — and on win32, GetLastInputInfo on the same schedule, which answers for the whole session the way the X counter does. On macOS it is the same schedule over the session's idle time: the @windowkit/appkit bridge's lastInputMs() (CoreGraphics' count, a call) where it has one, and otherwise ioreg's HIDIdleTime — a short-lived child process per check, which is one per timeout while the user is there and one every quarter of it, at most every half minute, while they are away. On an X display with neither extension it stays false.

Nothing is armed until a component subscribes, and the alarm or the poll stops when the last subscriber to that timeout unmounts.

timeout is a dependency, so hold it in a constant rather than building it inline from state that moves.

Keeping the screen on

useKeepAwake(playing, 'Playing a video');

Held while the flag is true and the component is mounted, released on either — including on an unmount mid-playback, which is the case that leaves a desktop permanently un-blanking when this is done by hand.

Four rungs. On win32, SetThreadExecutionState with ES_CONTINUOUS, which is what makes it a state rather than a one-shot nudge, and which is counted here so that one caller finishing does not speak for another. Elsewhere: the settings portal's Inhibit, the older org.freedesktop.ScreenSaver service, and ScreenSaverSuspend, which is a plain X request and needs no session bus at all. The three freedesktop rungs inhibit screen blanking only. Nothing there stops a suspend — only the portal rung could, and a seam that works on one desktop in three is worse than not offering it. The Windows rung asks for both the display and the system, which is the same call either way.

reason is shown by desktops that list what is holding the screen on, so it reads best as a sentence about the app's state rather than the app's name, which they already show. Windows takes no string with the call — powercfg /requests names the process — so there it is dropped rather than put somewhere the system will not show it.

Failure is silent by design: a machine with no portal, no screensaver service and no MIT-SCREEN-SAVER cannot be asked, and a video player is not the place to surface that. keepAwake() is the imperative twin, and resolves to the release.

`useKeyboardState()` — the locks and the layout

const { capsLock, layout } = useKeyboardState();

<PasswordInput value={password} onChange={setPassword} />;
{
  capsLock && <text style={{ color: theme.warning }}>Caps Lock is on</text>;
}


`capsLock` `numLock`	on or off, now
`group`	the active XKB group, `0`–`3`
`layout`	that group's layout code, `'ru'` — or null
`layouts`	every configured layout, `['us', 'ru']`

The point of the first row is that it is true of the keyboard rather than of an event. A key event carries the modifier state at the moment it was pressed, so an app can see that Caps Lock was on for a key it received — which is no help at all in the case that matters, a password field that wants to warn while it is merely focused and before anything has been typed.

The layout half is for a status-bar indicator, and for the other thing that costs people real time: a password typed in the wrong script, which looks identical to a wrong password. layout is a code rather than a description ('ru', not 'Russian') because that is what an indicator shows; uppercase it for display.

Everything here needs XKB, which Xorg and XQuartz both have. Where it is missing the locks read false and layouts is empty — so layouts is the field to check when the difference between "off" and "not known" matters. Changes arrive as XkbStateNotify, with no polling, even while another application has the keyboard.

Which bit is which lock is worth writing down: Caps Lock is LockMask, fixed by the core protocol, and Num Lock is not fixed by anything — it is wherever the modifier map puts it, which is Mod2 on every Linux and BSD desktop, on XQuartz, and in every toolkit that hardcodes it. This takes the convention.

`useDesktopSettings()` — how the desktop wants an app to feel

const { doubleClickMs, dragThreshold } = useDesktopSettings();


`caretBlink`	false means do not blink at all
`caretBlinkMs`	how long a caret stays in each state (530)
`doubleClickMs`	how long a second click has to arrive in (400)
`doubleClickDistance`	and how far it may land from the first (4px)
`dragThreshold`	how far a press moves before it is a drag (4px)
`animations`	false means reduce motion — see below
`source`	`'xsettings'`, or null where no settings daemon answered

The built-in controls already follow these. <textinput>'s caret, the click counting behind ev.detail, and the drag threshold all read the same values, so an app that uses the widget set gets this for nothing. The hook is for an app drawing its own: a <canvas> with a text cursor in it, a custom gesture, a diagram editor with its own drag. Reach for it so that one widget on the screen does not feel unlike every other.

animations is the desktop's "reduce motion", from GTK's gtk-enable-animations. Looping animations already honour it — a style.animation never starts while it is false, so <ProgressBar indeterminate> and anything else built on the loop primitive comes to rest with nothing to do. Transitions are left alone: a 120ms fade that ends is not the unbounded motion the setting exists for. Read the field where the resting look is a design decision your app has to make — a spinner that does not spin should still say it is working, which is what <ProgressBar indeterminate> does by filling its track instead.

caretBlink deserves the callout. A caret that ignores it is not a cosmetic miss: a moving thing on screen is what some people cannot read past, which is why the desktop offers the switch at all. Draw the caret solid rather than not at all — that is what the built-in controls do.

XSETTINGS is the only source on X11; there is no portal interface for any of this. On the macOS backend the one of these the system publishes is read from it: Reduce motion (System Settings › Accessibility › Display) arrives as animations: false with source: 'macos', live — flipping the switch stops a spinner that is already going round — and the other fields keep the defaults there, since macOS has no equivalent to hand over. On a desktop with no settings daemon — a bare startx, most window managers, XQuartz — source is null and the numbers above are this renderer's own defaults. They are deliberately not GTK's, which blinks on a 1200ms cycle and drags at 8px: the point is to follow a desktop that expressed a preference, not to change what happens on one that did not.

One seam worth knowing about. createRoot() starts XSETTINGS but does not await it — five round trips on every app's startup path, to answer a question that is not asked until the first interaction, is a bad trade. A field focused on the very first frame therefore gets the built-in default and the desktop's cadence from its next focus onward.

`createSettings()` — what the app remembers

The desktop's settings are read above; an app's own — the volume it was left at, the theme it was switched to — are kept here, in one JSON file per app in the per-user directory for it:

import { createSettings } from 'react-x11';

const settings = createSettings({
  appId: 'com.example.hush',
  defaults: { noiseType: 'brown', volume: 0.5, dark: false },
});

function Volume() {
  const [volume, setVolume] = settings.use('volume');
  return <Slider value={volume} onChange={setVolume} />;
}

settings.use(key) is a useState every component shares: every component using the key, in any window, sees one value, and setting it from one moves them all. It takes an updater function too, and settings.use(key, fallback) covers a key with no default.

platform	file
macOS	`~/Library/Application Support/<appId>/settings.json`
elsewhere	`$XDG_CONFIG_HOME/<appId>/settings.json` (`~/.config/…`)

The appId is a reverse-DNS name no other app uses, the shape registerApplication takes; the store registers nothing with it. Creating the store twice with the same id, in a module a hot reload evaluates again or in two call sites, is one store with one set of values.

It is read synchronously, the first time a value is asked for, so the first render already has what was saved rather than the defaults and then a jump. It is written asynchronously:

coalesced — a quarter second after the last change, and at least once a second while changes keep coming, so a drag on a slider is a few writes and not one per pointer move;
atomically — into a temporary file that is then renamed over the old one, so a crash mid-write leaves the file as it was, never half a file;
on exit — whatever is still unsaved when the process exits is written on the way out, including a change whose write was in flight. await settings.flush() writes it now.

Outside React, settings.get(key), settings.set(key, value), settings.reset(key) — the default again — and settings.subscribe(listener) are the same store. A value is whatever JSON can keep, and one it cannot, a function or a BigInt, is a TypeError at set. A file that is not JSON is reported once and the defaults stand; the next change replaces it.

Two copies of the app running at once share the file, and the last write wins: nothing watches for another process changing it.

`useLocale()` — the language and its conventions

const { locale, weekStartsOn } = useLocale();

// a date grid — `@react-x11/components`' <Calendar> takes both
<Calendar locale={locale} weekStartsOn={weekStartsOn} />;
<text>{new Intl.NumberFormat(locale).format(total)}</text>;


`locale`	a BCP-47 tag: `'en-GB'`, `'ru-RU'`
`direction`	`'ltr'` or `'rtl'`
`weekStartsOn`	`0` Sunday … `6` Saturday, from CLDR
`timeZone`	`'Europe/London'`, or null
`source`	`'env'` when `LANG` and friends said, `'intl'` when ICU did

LC_ALL / LC_MESSAGES / LANG win over Intl's own answer. node resolves Intl.DateTimeFormat().resolvedOptions().locale through ICU, and ICU answers what it has compiled in — a small-ICU build reports en-US for every environment there is. The POSIX variables are what the person who launched the app actually said. C and POSIX are not locales but the absence of one, so they fall through to ICU rather than becoming a tag.

This does not change while the app runs, and there is deliberately no subscription behind it: a process's environment is fixed at exec and ICU's resolution with it, so a desktop that switches language announces it for the next login and nothing this process can observe has moved.

For text direction inside a component prefer useDirection() over useLocale().direction — it also honours <ThemeProvider direction> and the direction style property, which the locale knows nothing about. See styling. The default theme is already seeded from the locale, so an app started under LANG=ar_EG.UTF-8 mirrors without being told to.

What is not here

Network status. There is no X-level answer, so it is necessarily D-Bus or netlink, and the honest version of the API would be a hint rather than a fact — a failed request is always the better truth than a flag that says the link is up. Not ruled out; not built.

Battery, brightness, volume, media keys. These are D-Bus services a third party can wrap without anything from here. Two things once on this list — the two desktop standards with a claim on core — are now built: notifications (notifications.md), and the tray, whose menu is dbusmenu this renderer already speaks — on the cocoa backend useTray() over NSStatusItem (#463), and on a freedesktop session over org.kde.StatusNotifierItem (#353) — D-Bus only, so the same rung serves X11, XWayland and Wayland.

The user's calendar. Their real events, from the accounts the desktop already holds — EventKit on macOS, Evolution Data Server on a freedesktop session — are desktop-calendar.md: useDesktopCalendarEvents(), keyed the way a calendar grid asks. It is not a system setting, which is why it is its own page rather than a hook here, but it is the same kind of thing as the rest of this one: something the desktop knows that an app would otherwise ask the user to type in again.

A launcher badge, and permission prompts. An unread count on the icon (freedesktop com.canonical.Unity.LauncherEntry, one D-Bus signal; macOS dockTile.badgeLabel) and camera/mic/location authorization (the freedesktop device portals; macOS TCC) are both cross-backend integrations with a D-Bus half that needs nothing from a native bridge — tracked in #464 and #466. Attention (the taskbar urgency / Dock bounce) already exists on X11 as states: ['demands_attention'].

Session lifecycle — "we are suspending, save now", and "I have unsaved work, do not log out yet". The X-native answer (XSMP) is effectively dead and the live one is logind. The shape worth having is probably not a system hook but a useBeforeQuit() that unifies it with <window onCloseRequest>. On the cocoa backend the second half already lands there: a quit request from the Dock, ⌘Q or a logout is routed to the primary window's onCloseRequest (uri-schemes.md, "On macOS").

useScreens() — the monitors​

The names arrive after the geometry​

available is an approximation on X11, and the only one here​

On Wayland​

On macOS the layout is asked for, not announced​

Mirroring​

useWindowState() — what the window manager did​

obscured and the compositor​

presenting, and the Wayland frame clock​

useIdle() and useKeepAwake() — is anyone there​

Keeping the screen on​

useKeyboardState() — the locks and the layout​

useDesktopSettings() — how the desktop wants an app to feel​

createSettings() — what the app remembers​

useLocale() — the language and its conventions​

What is not here​