Skip to content

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
confirm-dialog.svelte
<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
prompt-dialog.svelte
<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
alert-dialog.svelte
<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
custom-modal.svelte
<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>
ExampleCustomModal.svelte
<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>

From phoundry-ui@0.4.21

NameTypeDefaultDescription
titlerequiredstring—Modal title displayed in the header.
onCloserequired() => void—Called when the modal should close (escape, backdrop, close button).
closeOnBackdropbooleantrueAllow closing by clicking the backdrop overlay.
sizeModalSize—Named size controlling max-width (sm=400, md=560, lg=720, xl=960, full=100%).
widthstring—CSS inline size when size is omitted, such as 45rem or 90vw.
noTitlebooleanfalseHide the title bar for custom header layouts.
iconstring—Iconify icon id shown before the title. Ignored when noTitle is true.
iconColorstring—CSS color for the leading icon, such as var(--ph-accent). Defaults to the Theme secondary text color.
childrenrequiredSnippet<[]>—Modal body content.

Confirm Options

From phoundry-ui@0.4.21

NameTypeDefaultDescription
titlerequiredstring—Dialog heading.
messagerequiredstring—Dialog body text.
confirmLabelstring | undefined—Label for the confirm button.
cancelLabelstring | undefined—Label for the cancel button.
dangerboolean | undefined—Use danger variant for the confirm button.
iconstring | undefined—Iconify id for a leading icon.
iconColorstring | undefined—CSS color for the leading icon. Omit to use the semantic Theme default.

Prompt Options

From phoundry-ui@0.4.21

NameTypeDefaultDescription
titlerequiredstring—Dialog heading.
messagestring | undefined—Optional help text above the field.
defaultValuestring | undefined—Initial value for the input.
placeholderstring | undefined—Input placeholder text.
confirmLabelstring | undefined—Label for the submit button.
iconColorstring | undefined—CSS color for the leading icon. Omit to use the semantic Theme default.

Alert Options

From phoundry-ui@0.4.21

NameTypeDefaultDescription
titlerequiredstring—Dialog heading.
messagerequiredstring—Dialog body text.
confirmLabelstring | undefined—Label for the single action button.
iconstring | undefined—Iconify id; defaults to an information icon if omitted.
iconColorstring | 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 and ModalOverlay.
  • Use useModalManagerAPI() inside components (context-based) or getModalManager() from non-component code (global singleton).
  • manager.open(Component, props, options) returns a Promise that resolves when the modal closes, with the value passed to onClose(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.

Documentation is licensed under CC BY 4.0. Phoundry names and marks remain reserved.