# Email Compose Dialog
URL: /docs/web/docyrus/email-compose-dialog

A batteries-included launcher that opens the Docyrus EmailComposer (wired to the messaging API) inside a dialog, seeded with recipients/subject/body.

**Email Compose Dialog** opens the Docyrus [`EmailComposer`](/docs/web/components/email-composer)
inside a modal, fully wired to the tenant messaging API through
[`useDocyrusEmailComposer`](/docs/web/hooks/use-docyrus-email-composer). Give it a `client` and an
optional `to` / `cc` / `bcc` / `subject` / `body` seed and it handles account loading, sending, and a
success/error toast.

The composer body only mounts while the dialog is open, so each open re-reads the current seeds and
the `GET /v1/messaging/email/accounts` query fires only when visible. On a successful send it calls
`onSent(result)`, shows a toast, and closes.

The body editor's `@` mention autocomplete is active out of the box — the underlying hook loads the
tenant's users from `/v1/users` by default (see the hook's `mentions` option to disable).

It is the component behind the inline **compose** action on the
[`EmailFormField`](/docs/web/components/form-fields) and `EmailValue` renderer — pass a `client` to
those (directly or via `useDocyrusFormView` / `useDocyrusDataGrid` / `useDocyrusDataTable`) and the
action lights up automatically.

**Demo:**

```tsx
'use client';

import { Mail } from 'lucide-react';

import { Button } from '@docyrus/ui/primitives/ui/button';

export function EmailComposeDialogDemo() {
  return (
    <div className="flex w-full flex-col gap-3 rounded-lg border border-dashed border-border p-6 text-sm text-muted-foreground">
      <p>
        <code>{''}</code> requires an authenticated{' '}
        <code>RestApiClient</code> to list email accounts and send. Wire it up
        against your own Docyrus tenant (or the playground) to see it in action.
      </p>
      <div>
        
      </div>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-email-compose-dialog
```

**Dependencies:**
- [@tanstack/react-query](https://www.npmjs.com/package/@tanstack/react-query)
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [sonner](https://www.npmjs.com/package/sonner)
- [@docyrus/api-client](https://www.npmjs.com/package/@docyrus/api-client)

## Usage

### Standalone

```tsx
import { useDocyrusAuth } from '@docyrus/signin';
import { EmailComposeDialog } from '@docyrus/ui/components/email-compose-dialog';

function ContactActions({ email }: { email: string }) {
  const { client } = useDocyrusAuth();

  if (!client) return null;

  return (
    } />
```

### Automatic on fields, values, and grids

Pass a `client` to the email form field / value renderer (or let the Docyrus hooks thread it for you)
and the compose action appears with no extra wiring:

```tsx
// Form field + value renderer

// Whole form — useDocyrusFormView threads `client` into every field
const formView = useDocyrusFormView({ client, appSlug, dataSourceSlug, itemId });

// Grids — EmailCell (data grid) and EmailValue (data table) light up automatically
const grid = useDocyrusDataGrid({ client, appSlug, dataSourceSlug });
```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `client` | `RestApiClient` | — | Authenticated Docyrus REST client. **Required.** |
| `to` | `string[]` | — | Pre-filled recipients. |
| `cc` | `string[]` | — | Pre-filled Cc recipients. |
| `bcc` | `string[]` | — | Pre-filled Bcc recipients. |
| `subject` | `string` | — | Pre-filled subject. |
| `body` | `string` | — | Pre-filled body (HTML). |
| `trigger` | `ReactNode` | Ghost mail icon button | Custom element that opens the dialog. |
| `open` | `boolean` | — | Controlled open state. |
| `onOpenChange` | `(open: boolean) => void` | — | Open-state change handler. |
| `title` | `string` | `"Compose email"` | Dialog title. |
| `disabled` | `boolean` | `false` | Disables the default trigger button. |
| `sendAsUser` | `boolean` | — | Send through the tenant account with the user's identity (subject to account override rules). |
| `slashCommands` | `EmailComposerSlashCommand[]` | — | Developer-defined `/` slash commands forwarded to the composer body editor (see the [composer's Slash Commands section](/docs/web/components/email-composer#-slash-commands)). |
| `onSent` | `(result: DocyrusEmailSendResult) => void` | — | Called after a successful send. |
| `className` | `string` | — | Extra class for the default trigger button. |

## Related

- [`EmailComposer`](/docs/web/components/email-composer) — the presentational composer this dialog mounts.
- [`useDocyrusEmailComposer`](/docs/web/hooks/use-docyrus-email-composer) — the hook that wires the composer to the messaging API.
- [`InstantMessageComposeDialog`](/docs/web/docyrus/instant-message-compose-dialog) — the SMS / WhatsApp counterpart for phone fields.