---
title: useGameOverlay
description: "Manages help visibility and result configuration."
---

```tsx
import { useGameOverlay } from 'filedom';

const overlay = useGameOverlay({
  instructions: ['R - RESTART', '? - CLOSE'],
});
```

Configuration is read once on mount. The hook does not listen to the keyboard. Pass normalized keys to `overlay.onKey(key)`, or use [useGameControls](/docs/reference/hooks/use-game-controls), which listens for you and builds the help lines.

## Options

| Prop | Type | Default | Description |
| - | - | - | - |
| `instructions` | `string[]` | - | Help panel lines. |
| `winEffect?` | `WinEffectMode` | - | 'accent' (default) shows four accent icons on a win; 'none' turns them off. |
| `messages?` | `Partial<GameResultMessages>` | - | Overrides for the won, lost and draw text. Defaults: YOU WIN, GAME OVER, DRAW. |
| `help?` | `TextStyle` | - | How the ? help panel is drawn. Default { shape: { kind: 'sliced' }, onDemand: false }. |
| `banner?` | `TextStyle` | - | How the result banner is drawn. Default { shape: { kind: 'sliced' }, onDemand: false }. |

## TextStyle

```ts
type TextStyle = {
  shape?: TextShape;   // 'sliced' (default), 'glyphs', or 'grid'
  onDemand?: boolean;  // create the tiles on show so they draw over dragged icons
};
```

`shape` sets how large the text reads and how many files it costs, and
`onDemand` sets its z; see [Text](/docs/reference/components/text). In a drag-driven
game such as solitaire or chess, set `onDemand` on the banner so it draws over
dragged icons. A `grid` help panel avoids the problem a different way: the
overlay anchors it at the bottom of the desktop, clear of the play area.

```tsx
help: { shape: { kind: 'grid', charsPerCell: 3, linesPerCell: 2 } },
banner: { onDemand: true },
```

## Returns

`GameOverlayController`: `handle` (the resolved configuration), `showHelp`, `toggleHelp()`, and `onKey(key)`. `onKey` toggles help on `?` and returns whether it handled the key. Pass the controller to [GameOverlay](/docs/reference/components/game-overlay).