# useImperativeAlertDialog

## Usage

Hook for showing an alert dialog without managing open state. Call `alert.show(options)` to open and `alert.hide()` to close. Render `alert.Host` once in your template.

```ts
import { useImperativeAlertDialog } from '@astryx-vue/core/AlertDialog'
```

```vue
<script setup lang="ts">
import { useImperativeAlertDialog } from '@astryx-vue/core/AlertDialog'

const alert = useImperativeAlertDialog()
const AlertHost = alert.Host

function askToDelete(): void {
  alert.show({
    title: 'Delete item?',
    description: 'This action cannot be undone.',
    actionLabel: 'Delete',
    onAction: () => alert.hide(),
  })
}
</script>

<template>
  <button type="button" @click="askToDelete">
    Delete item
  </button>
  <AlertHost />
</template>
```

## Examples

Common configurations, variations, and states.

### useImperativeAlertDialog — Delete

A delete button that asks the user to confirm before deleting.

```vue
<script setup lang="ts">
import { useImperativeAlertDialog } from '@astryx-vue/core/AlertDialog'
import { Button } from '@astryx-vue/core/Button'

const alert = useImperativeAlertDialog()
const AlertHost = alert.Host

function confirmDelete(): void {
  alert.show({
    title: 'Delete item?',
    description: 'This action cannot be undone. The item and all its data will be permanently removed.',
    actionLabel: 'Delete',
    onAction: () => alert.hide(),
  })
}
</script>

<template>
  <div class="alert-dialog-preview">
    <Button label="Delete item" variant="destructive" @click="confirmDelete" />
    <AlertHost />
  </div>
</template>
```

## Returns

| Name | Type | Description |
| --- | --- | --- |
| `show` | `(options: ImperativeAlertDialogOptions) => void` | Show the alert dialog with the given options. Options are the same as `AlertDialog` props minus `isOpen`, plus `onAction`. |
| `hide` | `() => void` | Hide the alert dialog. |
| `isOpen` | `Ref<boolean>` | Whether the dialog is currently open. |
| `Host` | `Component` | The dialog element. Render it once in your template: `<component :is="alert.Host" />`. |

## Options

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | — | The question being asked. It names the dialog through `aria-labelledby`. Required. |
| `description` | `string` | — | What happens if the user confirms. It is linked through `aria-describedby`. Required. |
| `actionLabel` | `string` | — | Label for the confirming action. Say what will happen, such as `'Delete project'`. Required. |
| `onAction` | `(event: MouseEvent) => void` | — | Called when the confirming action is activated. The dialog is not closed for you: call `hide()` once the work settles. |
| `cancelLabel` | `string` | `'Cancel'` | Label for the cancel button. |
| `actionVariant` | `AlertDialogActionVariant` | `'destructive'` | Visual style of the confirming action. |
| `isActionLoading` | `boolean` | `false` | Shows a spinner on the confirming action while its work is in flight. |
| `width` | `number \| string` | `400` | Preferred width. Numbers are pixels, strings are used as-is. |