# Overlays manager (/docs/overlays)
The **overlays manager** spawns [`Modal`](/docs/modal)s and [`Drawer`](/docs/drawer)s on the fly — no `useState`, no JSX wiring at the call site. It's inspired by `@mantine/modals`, but adapted to Ark UI: a vanilla store + a thin renderer (the same shape as Ark's `createToaster`), so the imperative `overlays` object is callable from anywhere — event handlers, utilities, even outside React.
## Setup [#setup]
`createOverlays(config)` returns a bound `overlays` object, an `` renderer, and a `useOverlays()` hook. Call it once in a `"use client"` module and re-export the pieces:
```tsx title="app/overlays.ts"
'use client';
import { createOverlays } from '@42-central/ui-react/overlays';
export const { overlays, OverlaysProvider } = createOverlays({
labels: { confirm: 'Confirm', cancel: 'Cancel' },
});
```
Mount `` once near the root. It renders nothing until an overlay opens and is SSR-inert, so it's safe at the top of the tree:
```tsx title="app/layout.tsx"
import { OverlaysProvider } from './overlays';
export default function Layout({ children }) {
return (
{children}
);
}
```
Then call `overlays` from anywhere:
```tsx
import { overlays } from '@/app/overlays';
```
## Content overlays [#content-overlays]
`overlays.open` spawns an overlay with any content and returns its `id`.
## Confirm overlays [#confirm-overlays]
`overlays.openConfirm` adds confirm/cancel buttons (dogfooded `Button`s) and renders as an `alertdialog`. The confirm button awaits an async `onConfirm`, showing a spinner until it resolves.
## Drawers, from the same manager [#drawers-from-the-same-manager]
One stack, one descriptor with a `surface` field — so the manager spawns drawers too. Use `overlays.openDrawer`, or pass `surface: 'drawer'` to any method (e.g. a confirm in a drawer).
## Context overlays (typed) [#context-overlays-typed]
Register reusable overlay bodies by key, then open them with `overlays.openContext`. The registry type flows through generics, so `params` is **type-checked against the registered component** — no `declare module` augmentation.
```tsx title="app/overlays.ts"
import { createOverlays, type ContextOverlayProps } from '@42-central/ui-react/overlays';
function GreetModal({ context, params }: ContextOverlayProps<{ name: string }>) {
return (
Hello, {params.name}!
);
}
export const { overlays, OverlaysProvider } = createOverlays({
registry: { greet: GreetModal },
});
// elsewhere — params is checked against GreetModal's props:
overlays.openContext({ key: 'greet', params: { name: 'Ada' } });
```
## Stacking & dynamic updates [#stacking--dynamic-updates]
Overlays stack; `overlays.closeAll()` dismisses them all (each animates out independently). `overlays.update(id, patch)` patches an open overlay's options after it's shown.
## Reading live state [#reading-live-state]
`createOverlays` also returns a `useOverlays()` hook. Unlike the bound `overlays`
object — which is write-only handlers, callable from anywhere — `useOverlays()`
subscribes a component to the store and returns a `[entries, overlays]` tuple (à
la `useState`): the live overlay stack plus the same handlers.
```tsx
const [entries, overlays] = useOverlays();
// reactive: re-renders as overlays open and close
const openCount = entries.filter((e) => e.status === 'open').length;
```
`entries` is **typed against your registry**, so context entries discriminate on
`key` and expose typed `params` — no casting at the call site:
```tsx
for (const entry of entries) {
if (entry.kind === 'context' && entry.key === 'greet') {
entry.params.name; // string — checked against GreetModal's props
}
}
```
## API [#api]
`createOverlays(config)` config:
The returned `overlays` object:
Every `open*` method accepts the target surface's props (`size`, `centered`, `placement`, `closeOnEscape`, …) inline, plus an optional `surface: 'modal' | 'drawer'`.