---
title: "Dialogs and alerts"
description: "Programmatic dialogs, drawers, and alert/confirm/prompt overlays from @vinicunca/taman-ui/popup."
canonical_url: "https://vinicunca.dev/taman/guides/dialogs-and-alerts"
---
# Dialogs and alerts

> Programmatic dialogs, drawers, and alert/confirm/prompt overlays from @vinicunca/taman-ui/popup.

Import from `@vinicunca/taman-ui/popup`. Examples in the source repo live under `apps/web/src/views/examples/dialog` and `drawer` — those files are **stripped** from generated projects.

## Dialogs

```ts
import { useTamanDialog } from '@vinicunca/taman-ui/popup';

const [Dialog, dialogApi] = useTamanDialog({
  title: 'Edit todo',
  connectedComponent: TodoFormDialog, // optional Vue SFC
  onConfirm: async () => {
    dialogApi.lock();
    try {
      await save();
      dialogApi.close();
    } finally {
      dialogApi.unlock();
    }
  },
});
```

```vue
<template>
  <Dialog />
  <button
    type="button"
    @click="dialogApi.open()"
  >
    Open
  </button>
</template>
```

`useTamanDialog<TData, TConnectedComponent>(options?)` returns `[DialogComponent, api]`. Data can be inferred from the connected component or passed as `TData`.

### `DialogApi`

| Method | Role |
| --- | --- |
| `open()` | Sets `isOpen: true`, clears `submitting` |
| `close()` | Runs `onBeforeClose`; if it returns `false`, stays open |
| `setData(payload)` / `getData()` | Shared payload (`sharedData.payload`) |
| `setState(partial \| fn)` | Merge dialog UI state |
| `lock(true)` / `unlock()` | Disable cancel, spinner overlay, hide close, confirm loading |
| `onConfirm()` / `onCancel()` | Hook dispatch; default cancel calls `close()` |

Default state includes `closable: true`, `closeOnClickModal: true`, `closeOnPressEscape: true`, `destroyOnClose: true`, `footer: true`, `header: true`, `modal: true`, `animationType: 'slide'`.

`setDefaultDialogProps(props)` mutates process-wide defaults. Nested dialogs inject via `TAMAN_DIALOG_INJECT_KEY` so a child can extend the parent API.

Also exported: `createTamanDialog`, `TamanDialog`, dialog types.

## Drawers

Same shape as dialogs: `useTamanDrawer`, `createTamanDrawer`, `setDefaultDrawerProps`, `TamanDrawer`. API: `open` / `close` / `setData` / `lock` / `setState`. Use a drawer for forms that need more width than a modal.

## Alerts

These use Pohon `useOverlay` and `AlertOverlay`. They require the app to have installed `pohon-ui/vue-plugin` (Taman bootstrap already does).

```ts
import { clearAllAlerts, tamanAlert, tamanConfirm, tamanPrompt } from '@vinicunca/taman-ui/popup';

await tamanAlert({ title: 'Saved', content: 'Todo updated.' });

await tamanConfirm({ title: 'Delete?', content: 'This cannot be undone.' });
// rejects with Error('dialog cancelled') on cancel

const name = await tamanPrompt({
  title: 'Rename',
  defaultValue: current,
});
```

| Function | Behavior |
| --- | --- |
| `tamanAlert(options)` | Resolves on confirm; rejects on cancel. Default title from `useSimpleLocale()` (`prompt`) |
| `tamanConfirm(options)` | `tamanAlert` with `showCancel: true` |
| `tamanPrompt(options)` | Renders an input (default Pohon `PInput`) and resolves the value |
| `clearAllAlerts()` | Destroys every tracked overlay |

`tamanAlert` / confirm reject with `Error('dialog cancelled')` when the user dismisses. Catch that; do not treat it as an unexpected failure.

## Overlay z-index

Stacked overlays start at `Z_INDEX_OVERLAY_BASE` (1000) in taman-core constants, below `--taman-z-popup` (2000) so tooltips inside a dialog stay on top. `useOverlayZIndex` in taman-core composables implements the increment.


## Sitemap

See the full [sitemap](https://vinicunca.dev/sitemap.md) for all pages.