# useKeyboard

Subscribes to **global** keyboard events streamed from the Fluxlay desktop app. Useful for game-like wallpapers.

Every keystroke the user types anywhere on the desktop is delivered, regardless of which window has focus. Because **text typed into other apps also flows to the wallpaper**, treat this hook as if your wallpaper could be perceived as a keylogger and design accordingly.

## Permission declaration is required

To use this hook the wallpaper must declare the `keyboard` permission in `fluxlay.yaml`. Without the declaration the backend rejects the subscription with HTTP 403 and no events are delivered.

```yaml title="fluxlay.yaml"
schemaVersion: 1
name: My Wallpaper
slug: my-wallpaper
version: 1.0.0
permissions:
  - keyboard
```

See [`manifest`](/en/studio/developer/reference/cli/manifest.md#permissions) for the full permissions reference.

## Import

```tsx
import { useKeyboard } from "@fluxlay/react";
```

## Signature

```tsx
function useKeyboard(handlers: KeyboardHandlers): void;

interface KeyboardHandlers {
  onKeyDown?: (event: KeyEvent) => void;
  onKeyUp?: (event: KeyEvent) => void;
}
```

## Usage

```tsx
import { useKeyboard } from "@fluxlay/react";

function Wallpaper() {
  useKeyboard({
    onKeyDown: event => {
      console.log("down", event.code, event.modifiers, event.repeat);
    },
    onKeyUp: event => {
      console.log("up", event.code);
    }
  });
  return <div />;
}
```

## KeyEvent

| Property    | Type           | Description                                                                                                                                                                      |
| ----------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`      | `string`       | Physical key identifier following Web `KeyboardEvent.code` (e.g. `"KeyA"`, `"Space"`, `"Digit1"`, `"ArrowLeft"`, `"ShiftLeft"`). Unmapped keys come through as `"Unidentified"`. |
| `pressed`   | `boolean`      | `true` for key down, `false` for key up.                                                                                                                                         |
| `repeat`    | `boolean`      | Whether the OS reports this event as auto-repeat. On Windows the low-level hook does not surface a repeat flag, so this is derived by tracking the pressed-key set.              |
| `modifiers` | `KeyModifiers` | Modifier key state at the time of the event.                                                                                                                                     |

### KeyModifiers

| Property  | Type      | Description                           |
| --------- | --------- | ------------------------------------- |
| `shift`   | `boolean` | Shift key.                            |
| `control` | `boolean` | Control key.                          |
| `alt`     | `boolean` | Alt / Option key.                     |
| `meta`    | `boolean` | macOS Command key / Windows logo key. |

## Platform requirements

- **macOS**: the user must grant Fluxlay "Input Monitoring" permission (System Settings → Privacy & Security → Input Monitoring).
- **Windows**: the global hook may be flagged by some antivirus software. Key events targeting processes running at a higher integrity level (e.g. apps launched as Administrator) are not delivered, due to UIPI.