# dismiss

> Auto-dismiss behavior for an alert or notification host: counts down to dismissal, pausing while the pointer or focus is inside, and answers the `--ui-dismiss` invoker command from any trigger targeting the host.

```ts
import { dismiss } from "@sdxc/ui/mixins";
```

Adds an auto-dismiss countdown to a host, pausing while the pointer or
focus is inside, and answers the `--ui-dismiss` invoker command from any
trigger targeting it, dispatching DismissEvent either way.

## Signature

```ts
dismiss(options?: Dismiss.Options): MixinDescriptor<HTMLElement>
```

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `options?` | `Dismiss.Options` | Duration and hover-pause configuration; see Dismiss.Options. A call that omits it receives the mixin runtime's trailing current-props argument in its place, which is normalized back to an empty options object. |

## Examples

```tsx
<div id="toast-1" role="status" mix={[dismiss({ duration: 4000 })]}>
	Changes saved
	<button commandfor="toast-1" command="--ui-dismiss">Close</button>
</div>
```

```tsx
// An Alert that only ever dismisses through its own close button.
<div id="banner" role="alert" mix={[dismiss({ duration: null })]}>
	Your session expires soon.
	<button commandfor="banner" command="--ui-dismiss">Dismiss</button>
</div>
```

## Used with it

The events, constants and types its module publishes, each imported from `@sdxc/ui/mixins` too.

### DismissEvent

Dispatched on a host by dismiss when it dismisses, so a consumer
can remove the host from the page or from whatever queue produced it.

#### Signature

```ts
new DismissEvent(reason: Dismiss.Reason)
```

#### Properties

| Property | Type | Description |
| --- | --- | --- |
| `reason` | `readonly Dismiss.Reason` | What triggered this dismissal. |

### Dismiss.Options

Configuration accepted by dismiss.

#### Members

| Member | Type | Description |
| --- | --- | --- |
| `duration?` | `number \| null` | Milliseconds of visible, unpaused time before the host dismisses itself, or `null` to leave the timer disabled so the host only ever dismisses through the `--ui-dismiss` command. Defaults to 5000. |
| `pauseOnHover?` | `boolean` | Whether the countdown pauses while the pointer hovers the host or focus rests somewhere inside it, resuming from the time left once both leave. Defaults to `true`. |

### Dismiss.Reason

What triggered a dismissal: the auto-dismiss timer running out, or the `--ui-dismiss` invoker command firing.

#### Signature

```ts
type Dismiss.Reason = "timeout" | "manual"
```

One of `"timeout"`, `"manual"`.