Phi
Dialog
@dicehub/phiv1.7.0

Dialog

A window overlaid on the current page, rendering the content underneath inert.

<script setup>
import { Button } from "@dicehub/phi/components/button";
import { Dialog } from "@dicehub/phi/components/dialog";
</script>

<template>
  <Dialog.Root>
    <Dialog.Trigger>
      <Button>Save changes</Button>
    </Dialog.Trigger>

    <Dialog class="dialog-demo__panel">
      <div class="dialog-demo__header">
        <Dialog.Title class="dialog-demo__title">Save changes</Dialog.Title>
        <Dialog.Close />
      </div>
      <Dialog.Description>
        Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
      </Dialog.Description>
      <div class="dialog-demo__actions">
        <Dialog.Close as-child>
          <Button variant="secondary">Cancel</Button>
        </Dialog.Close>
        <Dialog.Close as-child><Button variant="primary">Save</Button></Dialog.Close>
      </div>
    </Dialog>
  </Dialog.Root>
</template>

Installation

Barrel

import { Dialog } from "@dicehub/phi";

Granular

import { Dialog } from "@dicehub/phi/components/dialog";

Usage

Dialogs open near the viewport top: 32px on small screens and 64px from 640px upward. This keeps long content visible and gives modal workflows a stable starting point.

Tall dialogs scroll inside the panel. The panel stays within the current viewport, and its final actions remain available by scroll or keyboard. LayerCard sections keep their natural height by default. Dialog does not set the flex sizing of other child elements.

<script setup>
import { Button } from "@dicehub/phi/components/button";
import { Dialog } from "@dicehub/phi/components/dialog";
</script>

<template>
  <Dialog.Root disable-pointer-dismissal>
    <Dialog.Trigger>
      <Button>Open</Button>
    </Dialog.Trigger>

    <Dialog>
      <Dialog.Title>Dialog Title</Dialog.Title>
      <Dialog.Description>Dialog content goes here.</Dialog.Description>
      <div class="dialog-demo__actions">
        <Dialog.Close as-child>
          <Button variant="secondary">Cancel</Button>
        </Dialog.Close>
      </div>
    </Dialog>
  </Dialog.Root>
</template>

Dialog vs Alert Dialog

Use role="dialog" for ordinary modal content and role="alertdialog" for destructive or confirmation flows. In an alert dialog, provide explicit footer actions such as Cancel and Delete. Omit the header close button. Set disablePointerDismissal on an ordinary dialog to keep it open when users click outside it.

RoleUse CaseBehavior
dialogForms, content display, short workflowsDismissible by default
alertdialogDestructive actions, critical confirmationsOutside pointer dismissal is disabled by default

Examples

Basic Dialog

<script setup>
import { Button } from "@dicehub/phi/components/button";
import { Dialog } from "@dicehub/phi/components/dialog";
</script>

<template>
  <Dialog.Root>
    <Dialog.Trigger>
      <Button>Click me</Button>
    </Dialog.Trigger>
    <Dialog class="dialog-demo__panel">
      <div class="dialog-demo__header">
        <Dialog.Title class="dialog-demo__title">Modal Title</Dialog.Title>
        <Dialog.Close />
      </div>
      <Dialog.Description>
        Lorem ipsum dolor sit amet, consectetur adipiscing elit.
      </Dialog.Description>
    </Dialog>
  </Dialog.Root>
</template>

Alert Dialog (role="alertdialog")

<script setup>
import { PhWarning } from "@phosphor-icons/vue";
import { Button } from "@dicehub/phi/components/button";
import { Dialog } from "@dicehub/phi/components/dialog";
</script>

<template>
  <Dialog.Root role="alertdialog">
    <Dialog.Trigger>
      <Button variant="destructive">Delete Account</Button>
    </Dialog.Trigger>
    <Dialog class="dialog-demo__panel dialog-demo__panel--alert">
      <div class="dialog-demo__header dialog-demo__header--icon">
        <span class="dialog-demo__warning"><PhWarning :size="20" weight="fill" /></span>
        <Dialog.Title class="dialog-demo__title dialog-demo__title--compact">Delete Account?</Dialog.Title>
      </div>
      <Dialog.Description>
        This action cannot be undone. All your data will be permanently removed from our servers. Are you sure you want to proceed?
      </Dialog.Description>
      <div class="dialog-demo__actions">
        <Dialog.Close as-child><Button variant="secondary">Cancel</Button></Dialog.Close>
        <Dialog.Close as-child><Button variant="destructive">Delete Account</Button></Dialog.Close>
      </div>
    </Dialog>
  </Dialog.Root>
</template>

Confirmation Dialog

<script setup>
import { PhWarning } from "@phosphor-icons/vue";
import { Button } from "@dicehub/phi/components/button";
import { Dialog } from "@dicehub/phi/components/dialog";
</script>

<template>
  <Dialog.Root role="alertdialog">
    <Dialog.Trigger>
      <Button variant="destructive">Delete Project</Button>
    </Dialog.Trigger>
    <Dialog class="dialog-demo__panel">
      <div class="dialog-demo__header dialog-demo__header--icon">
        <span class="dialog-demo__warning"><PhWarning :size="20" /></span>
        <Dialog.Title class="dialog-demo__title dialog-demo__title--compact">Delete Project?</Dialog.Title>
      </div>
      <Dialog.Description>
        This will permanently delete the project and all associated data.
      </Dialog.Description>
      <div class="dialog-demo__actions">
        <Dialog.Close as-child><Button variant="secondary">Cancel</Button></Dialog.Close>
        <Dialog.Close as-child><Button variant="destructive">Delete</Button></Dialog.Close>
      </div>
    </Dialog>
  </Dialog.Root>
</template>

With Actions

<script setup>
import { Button } from "@dicehub/phi/components/button";
import { Dialog } from "@dicehub/phi/components/dialog";
</script>

<template>
  <Dialog.Root>
    <Dialog.Trigger>
      <Button>Save changes</Button>
    </Dialog.Trigger>

    <Dialog class="dialog-demo__panel">
      <div class="dialog-demo__header">
        <Dialog.Title class="dialog-demo__title">Save changes</Dialog.Title>
        <Dialog.Close />
      </div>
      <Dialog.Description>
        Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
      </Dialog.Description>
      <div class="dialog-demo__actions">
        <Dialog.Close as-child>
          <Button variant="secondary">Cancel</Button>
        </Dialog.Close>
        <Dialog.Close as-child><Button variant="primary">Save</Button></Dialog.Close>
      </div>
    </Dialog>
  </Dialog.Root>
</template>

Max Width Override

<script setup>
import { Button } from "@dicehub/phi/components/button";
import { Dialog } from "@dicehub/phi/components/dialog";
</script>

<template>
  <Dialog.Root>
    <Dialog.Trigger>
      <Button>Open capped dialog</Button>
    </Dialog.Trigger>
    <Dialog class="dialog-demo__panel" style="--phi-dialog-width: 32rem; --phi-dialog-max-width: 32rem">
      <div class="dialog-demo__header">
        <Dialog.Title class="dialog-demo__title">Max width override</Dialog.Title>
        <Dialog.Close />
      </div>
      <Dialog.Description>
        Consumer styles can override the width token while the viewport cap remains active.
      </Dialog.Description>
    </Dialog>
  </Dialog.Root>
</template>

With Select

<script setup>
import { ref } from "vue";
import { Button } from "@dicehub/phi/components/button";
import { Dialog } from "@dicehub/phi/components/dialog";

const region = ref("us-east");
</script>

<template>
  <Dialog.Root>
    <Dialog.Trigger><Button>Open Form</Button></Dialog.Trigger>
    <Dialog class="dialog-demo__panel">
      <div class="dialog-demo__header">
        <Dialog.Title class="dialog-demo__title">Create Resource</Dialog.Title>
        <Dialog.Close />
      </div>
      <Dialog.Description>Select a region for the new resource.</Dialog.Description>
      <div class="dialog-demo__select-wrap">
        <select v-model="region" class="dialog-demo__select">
          <option value="us-east">US East</option>
          <option value="us-west">US West</option>
          <option value="eu-west">EU West</option>
        </select>
      </div>
      <div class="dialog-demo__actions">
        <Dialog.Close as-child><Button variant="secondary">Cancel</Button></Dialog.Close>
        <Dialog.Close as-child><Button variant="primary">Create</Button></Dialog.Close>
      </div>
    </Dialog>
  </Dialog.Root>
</template>

With Combobox

<script setup>
import { ref } from "vue";
import { Button } from "@dicehub/phi/components/button";
import { Combobox, createComboboxCollection } from "@dicehub/phi/components/combobox";
import { Dialog } from "@dicehub/phi/components/dialog";

const value = ref(["eu-west"]);
const regions = [
  { label: "US East", value: "us-east" },
  { label: "US West", value: "us-west" },
  { label: "EU West", value: "eu-west" },
];
const collection = createComboboxCollection({
  items: regions,
  itemToString: (item) => item.label,
  itemToValue: (item) => item.value,
});
</script>

<template>
  <Dialog.Root>
    <Dialog.Trigger><Button>Open Form</Button></Dialog.Trigger>
    <Dialog class="dialog-demo__panel">
      <Dialog.Title class="dialog-demo__title">Create Resource</Dialog.Title>
      <Dialog.Description>Search and select a region.</Dialog.Description>
      <Combobox v-model="value" :collection="collection">
        <Combobox.TriggerInput placeholder="Search regions" />
        <Combobox.Content>
          <Combobox.Empty />
          <Combobox.List>
            <template #default="{ item }">
              <Combobox.Item :item="item">{{ item.label }}</Combobox.Item>
            </template>
          </Combobox.List>
        </Combobox.Content>
      </Combobox>
      <div class="dialog-demo__actions">
        <Dialog.Close as-child><Button variant="secondary">Cancel</Button></Dialog.Close>
        <Dialog.Close as-child><Button variant="primary">Create</Button></Dialog.Close>
      </div>
    </Dialog>
  </Dialog.Root>
</template>

With Dropdown

<script setup>
import { Button } from "@dicehub/phi/components/button";
import { Dialog } from "@dicehub/phi/components/dialog";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from "@dicehub/phi/components/dropdown";
</script>

<template>
  <Dialog.Root>
    <Dialog.Trigger><Button>Open Form</Button></Dialog.Trigger>
    <Dialog class="dialog-demo__panel">
      <Dialog.Title class="dialog-demo__title">Resource Actions</Dialog.Title>
      <Dialog.Description>Choose an action for the selected resource.</Dialog.Description>
      <DropdownMenu>
        <DropdownMenuTrigger><Button>Actions</Button></DropdownMenuTrigger>
        <DropdownMenuContent>
        <DropdownMenuItem value="edit">Edit</DropdownMenuItem>
        <DropdownMenuItem value="duplicate">Duplicate</DropdownMenuItem>
        <DropdownMenuSeparator />
        <DropdownMenuItem value="delete" class="dialog-demo__dropdown-danger">Delete</DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
    </Dialog>
  </Dialog.Root>
</template>

Long Content

<script setup>
import { Button } from "@dicehub/phi/components/button";
import { Dialog } from "@dicehub/phi/components/dialog";
</script>

<template>
  <Dialog.Root>
    <Dialog.Trigger><Button>Open settings</Button></Dialog.Trigger>
    <Dialog style="padding: 1.5rem">
      <Dialog.Title>Review settings</Dialog.Title>
      <Dialog.Description>Read all settings before you save.</Dialog.Description>
      <div style="height: 900px">Long form content</div>
      <Dialog.Close as-child><Button>Save settings</Button></Dialog.Close>
    </Dialog>
  </Dialog.Root>
</template>

Scrollable Body

To keep the header and footer visible, make the dialog a flex column with hidden overflow. Give the bodyflex: 1, min-height: 0, and overflow-y: auto. ALayerCard.Primary or LayerCard.Secondary can also be the scrollable body; override its flex sizing with a CSS class or Tailwind's flex-1 utility.

<script setup>
import { Button } from "@dicehub/phi/components/button";
import { Dialog } from "@dicehub/phi/components/dialog";
</script>

<template>
  <Dialog.Root>
    <Dialog.Trigger><Button>Open settings</Button></Dialog.Trigger>
    <Dialog class="settings-dialog">
      <header><Dialog.Title>Settings</Dialog.Title></header>
      <div class="settings-dialog__body">
        <Dialog.Description>Review your settings before saving.</Dialog.Description>
        <!-- Long form content -->
      </div>
      <footer><Dialog.Close as-child><Button>Save settings</Button></Dialog.Close></footer>
    </Dialog>
  </Dialog.Root>
</template>

<style>
.settings-dialog { display: flex; flex-direction: column; overflow: hidden; }
.settings-dialog > header, .settings-dialog > footer { flex-shrink: 0; padding: 1rem; }
.settings-dialog__body { flex: 1; min-height: 0; overflow-y: auto; padding: 1rem; }
</style>

Sub-components

ComponentDescription
DialogMain modal surface that renders backdrop, positioner, and content.
Dialog.RootControls open state, modal behavior, role, and dismissal behavior.
Dialog.TriggerAs-child trigger that opens the dialog.
Dialog.TitleAccessible label for the dialog content.
Dialog.DescriptionAccessible supporting description.
Dialog.CloseClose trigger. Use as-child to render a Phi Button.

API Reference

Dialog

PropTypeDefaultDescription
size"sm" | "base" | "lg" | "xl""base"Width token for the modal surface.
teleportTostring | HTMLElement"body"Teleport target for backdrop and content.

Dialog.Root

PropTypeDefaultDescription
role"dialog" | "alertdialog""dialog"For alert dialogs, provide explicit footer actions instead of a header close button.
disablePointerDismissalbooleanfalsePrevents closing when the backdrop or outside area is clicked.
openboolean-Controlled open state forwarded to Ark UI.
closeOnEscapebooleantrueWhether Escape closes the dialog.

Dialog Parts

PropTypeDefaultDescription
asChildbooleanfalseAvailable on Dialog.Close to render a custom child control.
Ark propsDialog primitives-Trigger, Title, Description, and Close forward supported Ark attributes.