For the complete documentation index, see llms.txt. Markdown variants are available by appending .md to any URL or sending an Accept: text/markdown header. An agent skill is available at /.well-known/agent-skills/site-skill.md.
FrakmentFrakment

Dialog

A modal window that overlays the page and traps focus.

Web
Frakment
dialog.tsx
"use client";

import { XIcon } from "lucide-react";
import * as React from "react";
import { createPortal } from "react-dom";

import { getTransition, parseMotion, useReducedMotion } from "@/lib/motion";
import { cn } from "@/lib/utils";

interface DialogContextValue {
  contentRef: React.RefObject<HTMLDivElement | null>;
  descriptionId: string | null;
  open: boolean;
  setDescriptionId: (id: string | null) => void;
  setOpen: (open: boolean) => void;
  setTitleId: (id: string | null) => void;
  titleId: string | null;
  triggerRef: React.RefObject<HTMLElement | null>;
}

const DialogContext = React.createContext<DialogContextValue | null>(null);

function useDialogContext(): DialogContextValue {
  const ctx = React.useContext(DialogContext);
  if (!ctx) {
    throw new Error("Dialog components must be used within <Dialog>.");
  }
  return ctx;
}

const FOCUSABLE_SELECTOR =
  'a[href],button:not([disabled]),textarea:not([disabled]),input:not([disabled]),select:not([disabled]),[tabindex]:not([tabindex="-1"])';

function getFocusable(root: HTMLElement | null): HTMLElement[] {
  if (!root) {
    return [];
  }
  return Array.from(
    root.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)
  ).filter((el) => !el.hasAttribute("disabled") && el.offsetParent !== null);
}

interface DialogProps {
  children?: React.ReactNode;
  defaultOpen?: boolean;
  onOpenChange?: (open: boolean) => void;
  open?: boolean;
}

function Dialog({
  children,
  open: openProp,
  defaultOpen = false,
  onOpenChange,
}: DialogProps) {
  const isControlled = openProp !== undefined;
  const [uncontrolled, setUncontrolled] = React.useState(defaultOpen);
  const open = isControlled ? openProp : uncontrolled;
  const triggerRef = React.useRef<HTMLElement | null>(null);
  const contentRef = React.useRef<HTMLDivElement | null>(null);
  const [titleId, setTitleId] = React.useState<string | null>(null);
  const [descriptionId, setDescriptionId] = React.useState<string | null>(null);
  const setOpen = React.useCallback(
    (next: boolean) => {
      if (!isControlled) {
        setUncontrolled(next);
      }
      onOpenChange?.(next);
    },
    [isControlled, onOpenChange]
  );
  const ctx = React.useMemo<DialogContextValue>(
    () => ({
      contentRef,
      descriptionId,
      open,
      setDescriptionId,
      setOpen,
      setTitleId,
      titleId,
      triggerRef,
    }),
    [open, setOpen, titleId, descriptionId]
  );
  return (
    <DialogContext.Provider value={ctx}>
      <div data-slot="dialog" data-state={open ? "open" : "closed"}>
        {children}
      </div>
    </DialogContext.Provider>
  );
}

type DialogTriggerProps = Omit<
  React.ComponentPropsWithoutRef<"button">,
  "ref"
> &
  Record<string, unknown> & {
    as?: React.ElementType;
    asChild?: boolean;
    ref?: React.Ref<HTMLElement>;
  };

function DialogTrigger({
  as,
  asChild,
  children,
  onClick,
  ref,
  ...props
}: DialogTriggerProps) {
  const ctx = useDialogContext();
  const setRef = React.useCallback(
    (node: HTMLElement | null) => {
      ctx.triggerRef.current = node;
      if (typeof ref === "function") {
        ref(node);
      } else if (ref) {
        (ref as React.MutableRefObject<HTMLElement | null>).current = node;
      }
    },
    [ctx.triggerRef, ref]
  );
  const handleClick = (event: React.MouseEvent<HTMLElement>) => {
    onClick?.(event as never);
    if (event.defaultPrevented) {
      return;
    }
    ctx.setOpen(true);
  };
  if (asChild && React.isValidElement(children)) {
    const child = children as React.ReactElement<{
      onClick?: (e: React.MouseEvent<HTMLElement>) => void;
      ref?: React.Ref<HTMLElement>;
    }>;
    return React.cloneElement(child, {
      ...props,
      onClick: (event: React.MouseEvent<HTMLElement>) => {
        child.props.onClick?.(event);
        handleClick(event);
      },
      ref: setRef,
    } as never);
  }
  const Component = (as ?? "button") as React.ElementType;
  const isNativeButton = !as;
  return (
    <Component
      data-slot="dialog-trigger"
      {...props}
      {...(isNativeButton ? { type: "button" as const } : {})}
      onClick={handleClick}
      ref={setRef}
    >
      {children}
    </Component>
  );
}

function DialogPortal({ children }: { children?: React.ReactNode }) {
  return <>{children}</>;
}

type DialogCloseProps = Omit<React.ComponentPropsWithoutRef<"button">, "ref"> &
  Record<string, unknown> & {
    as?: React.ElementType;
    asChild?: boolean;
    ref?: React.Ref<HTMLElement>;
  };

function DialogClose({
  as,
  asChild,
  children,
  onClick,
  ref,
  ...props
}: DialogCloseProps) {
  const ctx = useDialogContext();
  const setRef = React.useCallback(
    (node: HTMLElement | null) => {
      if (typeof ref === "function") {
        ref(node);
      } else if (ref) {
        (ref as React.MutableRefObject<HTMLElement | null>).current = node;
      }
    },
    [ref]
  );
  const handleClick = (event: React.MouseEvent<HTMLElement>) => {
    onClick?.(event as never);
    if (event.defaultPrevented) {
      return;
    }
    ctx.setOpen(false);
  };
  if (asChild && React.isValidElement(children)) {
    const child = children as React.ReactElement<{
      onClick?: (e: React.MouseEvent<HTMLElement>) => void;
      ref?: React.Ref<HTMLElement>;
    }>;
    return React.cloneElement(child, {
      ...props,
      onClick: (event: React.MouseEvent<HTMLElement>) => {
        child.props.onClick?.(event);
        handleClick(event);
      },
      ref: setRef,
    } as never);
  }
  const Component = (as ?? "button") as React.ElementType;
  const isNativeButton = !as;
  return (
    <Component
      data-slot="dialog-close"
      {...props}
      {...(isNativeButton ? { type: "button" as const } : {})}
      onClick={handleClick}
      ref={setRef}
    >
      {children}
    </Component>
  );
}

type DialogOverlayProps = React.ComponentPropsWithoutRef<"div"> & {
  motion?: string;
};

function DialogOverlay({
  className,
  motion,
  style,
  ...props
}: DialogOverlayProps) {
  const ctx = useDialogContext();
  const reduce = useReducedMotion();
  const transition = reduce
    ? "none"
    : (getTransition(parseMotion(motion)) ?? "opacity 150ms ease-out");
  return (
    <div
      aria-hidden="true"
      className={className}
      data-slot="dialog-overlay"
      data-state={ctx.open ? "open" : "closed"}
      {...props}
      onClick={(event) => {
        if (event.target === event.currentTarget) {
          ctx.setOpen(false);
        }
      }}
      style={{
        background: "rgba(0,0,0,0.5)",
        inset: 0,
        opacity: ctx.open ? 1 : 0,
        position: "fixed",
        transition,
        zIndex: 50,
        ...style,
      }}
    />
  );
}

type DialogContentProps = React.ComponentPropsWithoutRef<"div"> & {
  showCloseButton?: boolean;
  motion?: string;
};

function DialogContent({
  children,
  className,
  motion,
  showCloseButton = true,
  style,
  ...props
}: DialogContentProps) {
  const ctx = useDialogContext();
  const { open, setOpen, contentRef, triggerRef, titleId, descriptionId } = ctx;
  const reduce = useReducedMotion();
  const [mounted, setMounted] = React.useState(false);
  const [entered, setEntered] = React.useState(false);
  const transition = reduce
    ? "none"
    : (getTransition(parseMotion(motion)) ??
      "opacity 150ms ease-out, transform 150ms ease-out");
  React.useEffect(() => {
    if (open) {
      setMounted(true);
      const r1 = requestAnimationFrame(() => {
        const r2 = requestAnimationFrame(() => setEntered(true));
        return () => cancelAnimationFrame(r2);
      });
      return () => cancelAnimationFrame(r1);
    }
    setEntered(false);
    const t = setTimeout(() => setMounted(false), 150);
    return () => clearTimeout(t);
  }, [open]);
  React.useEffect(() => {
    if (!(open && mounted)) {
      return;
    }
    const prev = document.activeElement as HTMLElement | null;
    const root = contentRef.current;
    if (root) {
      const f = getFocusable(root);
      (f[0] ?? root).focus();
    }
    return () => {
      if (prev && typeof prev.focus === "function") {
        prev.focus();
      } else {
        triggerRef.current?.focus?.();
      }
    };
  }, [open, mounted, contentRef, triggerRef]);
  React.useEffect(() => {
    if (!open) {
      return;
    }
    const onKey = (event: KeyboardEvent) => {
      if (event.key === "Escape") {
        event.stopPropagation();
        setOpen(false);
        return;
      }
      if (event.key !== "Tab") {
        return;
      }
      const root = contentRef.current;
      if (!root) {
        return;
      }
      const f = getFocusable(root);
      if (f.length === 0) {
        event.preventDefault();
        root.focus();
        return;
      }
      const first = f[0];
      const last = f.at(-1);
      if (!last) {
        return;
      }
      const active = document.activeElement as HTMLElement | null;
      if (event.shiftKey && active === first) {
        event.preventDefault();
        last.focus();
      } else if (!event.shiftKey && active === last) {
        event.preventDefault();
        first.focus();
      }
    };
    document.addEventListener("keydown", onKey);
    return () => document.removeEventListener("keydown", onKey);
  }, [open, setOpen, contentRef]);
  if (!mounted) {
    return null;
  }
  if (typeof document === "undefined") {
    return null;
  }
  const content = (
    <>
      <DialogOverlay motion={motion} />
      <div
        aria-describedby={descriptionId ?? undefined}
        aria-labelledby={titleId ?? undefined}
        aria-modal="true"
        className={cn(
          "bg-background fixed top-[50%] left-[50%] z-50 grid w-full max-w-[calc(100%-2rem)] gap-4 rounded-lg border p-6 shadow-lg sm:max-w-lg",
          className
        )}
        data-slot="dialog-content"
        data-state={open ? "open" : "closed"}
        ref={contentRef}
        role="dialog"
        tabIndex={-1}
        {...props}
        style={{
          opacity: entered ? 1 : 0,
          overscrollBehavior: "contain",
          transform: `translate(-50%, -50%) scale(${entered ? 1 : 0.95})`,
          transition,
          ...style,
        }}
      >
        {children}
        {showCloseButton && (
          <DialogClose className="ring-offset-background focus:ring-ring absolute top-4 right-4 rounded-xs opacity-70 transition-opacity hover:opacity-100 focus:ring-2 focus:ring-offset-2 focus:outline-hidden disabled:pointer-events-none [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*=size-])]:size-4">
            <XIcon />
            <span className="sr-only">Close</span>
          </DialogClose>
        )}
      </div>
    </>
  );
  return createPortal(content, document.body);
}

const DialogHeader = ({ className, ...props }: React.ComponentProps<"div">) => (
  <div
    className={cn("flex flex-col gap-2 text-center sm:text-left", className)}
    data-slot="dialog-header"
    {...props}
  />
);

const DialogFooter = ({ className, ...props }: React.ComponentProps<"div">) => (
  <div
    className={cn(
      "flex flex-col-reverse gap-2 sm:flex-row sm:justify-end",
      className
    )}
    data-slot="dialog-footer"
    {...props}
  />
);

const DialogTitle = ({
  className,
  id,
  ...props
}: React.ComponentProps<"h2">) => {
  const ctx = useDialogContext();
  const generatedId = React.useId();
  const titleId = id ?? generatedId;
  React.useEffect(() => {
    ctx.setTitleId(titleId);
    return () => ctx.setTitleId(null);
  }, [ctx, titleId]);
  return (
    <h2
      className={cn("text-lg leading-none font-semibold", className)}
      data-slot="dialog-title"
      id={titleId}
      {...props}
    />
  );
};

const DialogDescription = ({
  className,
  id,
  ...props
}: React.ComponentProps<"p">) => {
  const ctx = useDialogContext();
  const generatedId = React.useId();
  const descId = id ?? generatedId;
  React.useEffect(() => {
    ctx.setDescriptionId(descId);
    return () => ctx.setDescriptionId(null);
  }, [ctx, descId]);
  return (
    <p
      className={cn("text-muted-foreground text-sm", className)}
      data-slot="dialog-description"
      id={descId}
      {...props}
    />
  );
};

export {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogOverlay,
  DialogPortal,
  DialogTitle,
  DialogTrigger,
};

Dialog renders a modal that overlays the page and traps focus until dismissed.

Installation

Usage

dialog.tsx
import {
  Dialog, DialogClose, DialogContent, DialogDescription,
  DialogFooter, DialogHeader, DialogTitle, DialogTrigger,
} from "@/components/ui/dialog";
tsx
<Dialog>
  <DialogTrigger as={Button}>Open</DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Title</DialogTitle>
      <DialogDescription>Description</DialogDescription>
    </DialogHeader>
    <DialogFooter>
      <DialogClose as={Button} variant="outline">Cancel</DialogClose>
      <Button>Save</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>

Composition

Dialog
├── DialogTrigger
└── DialogContent
    ├── DialogHeader
    │   ├── DialogTitle
    │   └── DialogDescription
    ├── DialogFooter
    └── DialogClose

Examples

With close button

A dialog with an inline Close button instead of the corner X.

dialog-close-button.tsx
import { Button } from "@/components/ui/button";
import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog";
import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";

export function DialogCloseButton() {
  return (
    <Dialog>
      <DialogTrigger as={Button} variant="outline">
        Share
      </DialogTrigger>
      <DialogContent className="sm:max-w-md">
        <DialogHeader>
          <DialogTitle>Share link</DialogTitle>
          <DialogDescription>
            Anyone who has this link will be able to view this.
          </DialogDescription>
        </DialogHeader>
        <div className="flex items-center gap-2">
          <div className="grid flex-1 gap-2">
            <Label className="sr-only" htmlFor="link">
              Link
            </Label>
            <Input
              defaultValue="https://frakment.dev/docs/installation"
              id="link"
              readOnly
            />
          </div>
        </div>
        <DialogFooter className="sm:justify-start">
          <DialogClose as={Button} type="button">
            Close
          </DialogClose>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  );
}

Without close button

Pass showCloseButton={false} and dismiss via backdrop or Escape.

dialog-no-close-button.tsx
import { Button } from "@/components/ui/button";
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog";

export function DialogNoCloseButton() {
  return (
    <Dialog>
      <DialogTrigger as={Button} variant="outline">
        No Close Button
      </DialogTrigger>
      <DialogContent showCloseButton={false}>
        <DialogHeader>
          <DialogTitle>No Close Button</DialogTitle>
          <DialogDescription>
            This dialog does not have a close button in the top-right corner.
          </DialogDescription>
        </DialogHeader>
      </DialogContent>
    </Dialog>
  );
}

Scrollable body with a footer that stays pinned to the bottom.

dialog-sticky-footer.tsx
import { Button } from "@/components/ui/button";
import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog";

export function DialogStickyFooter() {
  return (
    <Dialog>
      <DialogTrigger as={Button} variant="outline">
        Sticky Footer
      </DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Sticky Footer</DialogTitle>
          <DialogDescription>
            This dialog has a sticky footer that stays visible while the content
            scrolls.
          </DialogDescription>
        </DialogHeader>
        <div className="no-scrollbar -mx-4 max-h-[50vh] overflow-y-auto px-4">
          {[1, 2, 3, 4, 5].map((n) => (
            <p className="mb-4 leading-normal" key={n}>
              Section {n}. The quick brown fox jumps over the lazy dog. Pack my
              box with five dozen liquor jugs. How vexingly quick daft zebras
              jump. Sphinx of black quartz, judge my vow. Two driven jocks help
              fax my big quiz. The five boxing wizards jump quickly. Jackdaws
              love my big sphinx of quartz. Bright vixens jump; dozy fowl quack.
            </p>
          ))}
        </div>
        <DialogFooter>
          <DialogClose as={Button} variant="outline">
            Close
          </DialogClose>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  );
}

Scrollable content

Long content scrolls inside the dialog without growing it past the viewport.

dialog-scrollable-content.tsx
import { Button } from "@/components/ui/button";
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog";

export function DialogScrollableContent() {
  return (
    <Dialog>
      <DialogTrigger as={Button} variant="outline">
        Scrollable Content
      </DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Scrollable Content</DialogTitle>
          <DialogDescription>
            This is a dialog with scrollable content.
          </DialogDescription>
        </DialogHeader>
        <div className="no-scrollbar -mx-4 max-h-[50vh] overflow-y-auto px-4">
          {[1, 2, 3, 4, 5].map((n) => (
            <p className="mb-4 leading-normal" key={n}>
              Section {n}. The quick brown fox jumps over the lazy dog. Pack my
              box with five dozen liquor jugs. How vexingly quick daft zebras
              jump. Sphinx of black quartz, judge my vow. Two driven jocks help
              fax my big quiz. The five boxing wizards jump quickly. Jackdaws
              love my big sphinx of quartz. Bright vixens jump; dozy fowl quack.
            </p>
          ))}
        </div>
      </DialogContent>
    </Dialog>
  );
}

In Context

Confirm deletion

dialog-confirm.tsx
"use client";

import { Button } from "@/components/ui/button";
import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog";

export function DialogConfirm() {
  return (
    <Dialog>
      <DialogTrigger as={Button} variant="destructive">
        Delete file
      </DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Delete this file?</DialogTitle>
          <DialogDescription>This cannot be undone.</DialogDescription>
        </DialogHeader>
        <DialogFooter>
          <DialogClose as={Button} variant="outline">
            Cancel
          </DialogClose>
          <Button variant="destructive">Delete</Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  );
}

Data Attributes

AttributeValuesApplies to
data-slotdialog-trigger, dialog-content, dialog-header, dialog-footer, dialog-title, dialog-description, dialog-closePer sub-component
data-stateopen | closedDialog, DialogContent, DialogOverlay

Use these in CSS or tests to target the current state:

tsx
<DialogContent className="data-[state=open]:opacity-100 data-[state=closed]:opacity-0" />

Keyboard

KeyAction
EscClose the dialog
TabMove focus forward
Shift + TabMove focus backwards
Enter / SpaceActivate focused element

Focus is trapped inside DialogContent while open. On close, focus returns to the trigger.

Controlled

Without open, the dialog manages its own state. Pass open and onOpenChange to control it:

tsx
const [open, setOpen] = React.useState(false)
 
<Dialog open={open} onOpenChange={setOpen}>
  <DialogTrigger as={Button}>Open</DialogTrigger>
  <DialogContent>{/* ... */}</DialogContent>
</Dialog>

Use defaultOpen for an uncontrolled dialog that starts open.

As Prop

DialogTrigger and DialogClose accept an as prop to render a custom element:

tsx
<DialogTrigger as={Button} variant="outline">Settings</DialogTrigger>

Without as, the trigger renders as a native <button>.

Motion

DialogContent accepts a motion prop to customize the entrance and exit timing:

tsx
<DialogContent motion="200 ease-out">{/* ... */}</DialogContent>

The default is 150ms ease-out. motion="off" disables the animation. prefers-reduced-motion is always respected.

API Reference

DialogContent

PropTypeDefaultDescription
showCloseButtonbooleantrueShow the top-right close button.
motionstring150ms ease-outEntrance/exit timing. Set to off to disable.
classNamestring—Extra classes on the modal panel.

Accessibility

  • Focus is trapped inside the dialog while open.
  • DialogTitle and DialogDescription are announced to screen readers via aria-labelledby and aria-describedby.
  • Escape closes the dialog.
  • Clicking the backdrop closes the dialog.
  • role="dialog" and aria-modal="true" are set on DialogContent.

Best Practices

  • Do not use a dialog for navigation. Use a sheet or a new route instead.
  • Keep content short. If it needs to scroll, it might belong on its own page.
  • Provide multiple exits. Cancel in the footer, Escape key, and outside click.
  • Put the destructive action last. Primary on the right, destructive on the far right.
  • Sheet — modal panel that slides in from an edge
  • Dropdown Menu — action menu anchored to a trigger
  • Tooltip — short hint on hover