Modal
Stack-based modal system with a programmatic API. Includes built-in confirm, prompt, and alert dialogs, or pass your own Svelte component to open().
import { useModalManagerAPI, Modal } from "phoundry-ui";Confirm Dialog
Loading interactive example…
View source
<script lang="ts"> import { Button } from "phoundry-ui"; import { useModalManagerAPI } from "phoundry-ui";
const manager = useModalManagerAPI();
let confirmResult = $state<boolean | null>(null);
async function handleConfirm() { confirmResult = await manager.confirm({ title: "Delete Item", message: "Are you sure you want to delete this item? This action cannot be undone.", confirmLabel: "Delete", danger: true, }); }</script>
<div class="flex items-center gap-3"> <Button variant="danger" onclick={handleConfirm}>Open Confirm</Button> {#if confirmResult !== null} <span class="text-xs text-txt-secondary"> Result: {confirmResult ? "Confirmed" : "Cancelled"} </span> {/if}</div>Prompt Dialog
Loading interactive example…
View source
<script lang="ts"> import { Button } from "phoundry-ui"; import { useModalManagerAPI } from "phoundry-ui";
const manager = useModalManagerAPI();
let promptResult = $state<string | null>(null);
async function handlePrompt() { promptResult = await manager.prompt({ title: "Rename File", message: "Enter a new name for the file:", defaultValue: "untitled.txt", placeholder: "filename", icon: "lucide:file-pen", iconColor: "var(--ph-text-tertiary)", }); }</script>
<div class="flex items-center gap-3"> <Button onclick={handlePrompt}>Open Prompt</Button> {#if promptResult !== null} <span class="text-xs text-txt-secondary">Result: "{promptResult}"</span> {/if}</div>Alert Dialog
Loading interactive example…
View source
<script lang="ts"> import { Button } from "phoundry-ui"; import { useModalManagerAPI } from "phoundry-ui";
const manager = useModalManagerAPI();
async function handleAlert() { await manager.alert({ title: "Update Complete", message: "Your settings have been saved successfully.", }); }</script>
<div class="flex flex-wrap items-center gap-3"> <Button onclick={handleAlert}>Default alert</Button></div>Custom modal
Loading interactive example…
View source
<script lang="ts"> import { Button } from "phoundry-ui"; import { useModalManagerAPI } from "phoundry-ui"; import ExampleCustomModal from "../../_shared/ExampleCustomModal.svelte";
const manager = useModalManagerAPI();
let customResult = $state<"exported" | "archived" | undefined | null>(null);
async function handleCustomModal() { customResult = await manager.open<"exported" | "archived" | undefined>( ExampleCustomModal, { projectName: "Northwind" }, { closeOnBackdrop: false, icon: "mdi:folder-outline", iconColor: "var(--ph-text-tertiary)", }, ); }</script>
<div class="flex items-center gap-3"> <Button onclick={handleCustomModal}>Open custom modal</Button> {#if customResult !== null} <span class="text-xs text-txt-secondary"> Result: {#if customResult === undefined} dismissed {:else if customResult === "exported"} exported {:else} archived {/if} </span> {/if}</div><script lang="ts"> import Icon from "@iconify/svelte"; import { Button } from "phoundry-ui";
interface Props { projectName: string; onClose: (result?: "exported" | "archived") => void; icon?: string; iconColor?: string; }
let { projectName, onClose, icon, iconColor }: Props = $props();</script>
<div class="modal-panel w-96 max-w-[90vw]"> <div class="flex items-center gap-2 px-3 py-2.5"> {#if icon} <Icon {icon} width={16} height={16} class="shrink-0" style={`color: ${iconColor ?? "var(--ph-text-tertiary)"};`} /> {/if} <h2 class="text-sm font-medium text-txt-primary">Project actions</h2> </div> <div class="-mt-1 px-3 pb-2.5"> <p class="mt-1 text-sm text-txt-secondary"> What should happen to <span class="font-medium text-txt-primary" >{projectName}</span >? </p> </div> <div class="flex flex-col gap-1 px-3 pb-2"> <Button variant="ghost" class="justify-start" onclick={() => onClose("exported")}>Export snapshot</Button > <Button variant="ghost" class="justify-start" onclick={() => onClose("archived")}>Archive project</Button > </div> <div class="flex justify-end px-3 py-2.5"> <Button variant="ghost" onclick={() => onClose()}>Cancel</Button> </div></div>Modal Props
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
titlerequired | string | — | Modal title displayed in the header. |
onCloserequired | () => void | — | Called when the modal should close (escape, backdrop, close button). |
closeOnBackdrop | boolean | true | Allow closing by clicking the backdrop overlay. |
size | ModalSize | — | Named size controlling max-width (sm=400, md=560, lg=720, xl=960, full=100%). |
width | string | — | CSS inline size when size is omitted, such as 45rem or 90vw. |
noTitle | boolean | false | Hide the title bar for custom header layouts. |
icon | string | — | Iconify icon id shown before the title. Ignored when noTitle is true. |
iconColor | string | — | CSS color for the leading icon, such as var(--ph-accent). Defaults to the Theme secondary text color. |
childrenrequired | Snippet<[]> | — | Modal body content. |
Confirm Options
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
titlerequired | string | — | Dialog heading. |
messagerequired | string | — | Dialog body text. |
confirmLabel | string | undefined | — | Label for the confirm button. |
cancelLabel | string | undefined | — | Label for the cancel button. |
danger | boolean | undefined | — | Use danger variant for the confirm button. |
icon | string | undefined | — | Iconify id for a leading icon. |
iconColor | string | undefined | — | CSS color for the leading icon. Omit to use the semantic Theme default. |
Prompt Options
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
titlerequired | string | — | Dialog heading. |
message | string | undefined | — | Optional help text above the field. |
defaultValue | string | undefined | — | Initial value for the input. |
placeholder | string | undefined | — | Input placeholder text. |
confirmLabel | string | undefined | — | Label for the submit button. |
iconColor | string | undefined | — | CSS color for the leading icon. Omit to use the semantic Theme default. |
Alert Options
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
titlerequired | string | — | Dialog heading. |
messagerequired | string | — | Dialog body text. |
confirmLabel | string | undefined | — | Label for the single action button. |
icon | string | undefined | — | Iconify id; defaults to an information icon if omitted. |
iconColor | string | undefined | — | CSS color for the leading icon. Omit to use the semantic Theme default. |
Usage tips
- Call
setupOverlays()once in your root layout to initialize all overlay managers together, including the modal stack andModalOverlay. - Use
useModalManagerAPI()inside components (context-based) orgetModalManager()from non-component code (global singleton). manager.open(Component, props, options)returns aPromisethat resolves when the modal closes, with the value passed toonClose(result).- Modals stack - opening a second modal layers it on top.
manager.closeAll()dismisses the entire stack.
Mobile keyboard
Set mobile once on the overlay in your root layout to keep every modal in the
visible viewport when the on-screen keyboard opens:
<ModalOverlay mobile={isMobileClient} />mobile defaults to false. Enable it from the application’s native platform
identity. The overlay follows visual viewport resize and scroll events, recenters
the entire modal stack above the keyboard, and leaves pinch zoom to the browser.
The library Modal panel also limits its height to the available space. Custom
dialogs should use a scrollable body for long content.
CSS styling
.ph-modal is the stable identification hook for Modal. Part selectors and --_ph-* properties are internal. Component CSS is scoped and unlayered; Consumer classes remain additive and utility overrides may lose precedence.
The content panel uses .ph-modal-panel. AlertDialog, ConfirmDialog, and PromptDialog use .ph-alert-dialog, .ph-confirm-dialog, and .ph-prompt-dialog. Named panel sizes are sm 25rem, md 35rem, lg 45rem, xl 60rem, and full the window width minus 2rem. Without a named size, width accepts a CSS inline size and defaults to 24rem. Class strings are no longer accepted for width or iconColor. All built-in dialogs and manager options accept CSS colors for iconColor, such as var(--ph-accent). --ph-modal-panel-height caps panel height; the existing --phi-modal-panel-height alias is still accepted.
Keep the shared component stylesheet and a named Theme imported. Decorative motion respects reduced-motion preferences.
For custom modal content, apply the shared .ph-dialog-panel visual surface explicitly. The former .modal-panel class remains a compatibility alias.