Build Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.
Overlays
Dify UI overlay primitives own their Base UI portals, normal application layer, positioning, focus, modal behavior, and dismissal contracts. Consumers choose the semantic primitive and compose its exported anatomy instead of recreating those responsibilities.
Portals and root isolation
Floating surfaces render through Base UI Portal into document.body. Convenience components
such as DialogContent, PopoverContent, and SelectContent own their portals internally;
primitives with explicit anatomy expose the constituent portal and content parts.
Mounting and state lifetime
An overlay root's React lifetime, its open state, and its portal subtree's presence are separate.
Presence is part of each primitive's contract. Convenience content follows its primitive's
default mount behavior; for example, DialogContent owns a Dialog.Portal whose subtree mounts
when the dialog opens and unmounts after any close transition completes. The Dialog root may
remain mounted and controlled independently of that content lifetime. Removing the controlled
root with the same condition that closes it bypasses the primitive's closing lifecycle.
Application code can use an unmounting content subtree as the owner of state scoped to one mounted
content session. State that must survive the subtree's unmount belongs to an explicit longer-lived
feature owner.
Unmounting resets only DOM and component state owned inside that subtree; state declared by an
ancestor or external store survives. Portal placement alone is not a reset boundary.
Consumers using explicit anatomy may opt into keepMounted where that portal supports it; they
must then define which state persists and which state resets instead of relying on a remount.
Check the selected primitive's API rather than assuming every overlay portal has the same presence
options.
The host must establish an isolated stacking context at its application root:
<body>
<div className="isolate">{children}</div>
</body>
Equivalent CSS is isolation: isolate. It creates a stacking context so
application descendants cannot use high z-index values to compete with sibling surfaces portalled
to body. Portalling avoids clipping by application ancestors; isolation itself does not fix
clipping.
Layering
Overlays set no z-index; portal DOM order stacks them. A Base UI modal blocks outside clicks with an unstyled sibling of its popup, so any overlay z-index can lift a lower layer above that guard. Only a body-level layer that must stay above overlays mounted after it sets one. A portal into an application container sits inside the isolated root and layers against its siblings there.
Positioners hide with their anchor: Base UI marks them data-anchor-hidden when the anchor is
clipped, display: none or unmounted, and the shared positioner class turns that into
visibility: hidden plus pointer-events: none so a popup never lingers at the viewport origin.
- Do not add call-site
z-*overrides or force a backdrop to block clicks. Fix the owning overlay structure when content is clipped, hidden, or clickable behind a modal. - Do not wrap a Dify UI overlay in another manual portal.
- Add shared backdrop or presentation chrome inside the owning exported component, not at call sites.
Primitive semantics
- Use
Dialogfor modal content that needs focus containment and scroll locking.DialogContentis the centered modal surface: composeDialogHeader,DialogBodyandDialogFooterin it, andDialogBodyscrolls between the other two. A wrapper between the surface and its parts, such as a form, keeps the flex chain withcontents.DialogPopupis the bare dialog element for a surface that places and dresses itself.DialogContentandAlertDialogContentallowtransition-none, including state variants, without requiring custom popup composition.DialogHeaderCloseButtonis the optional standard close icon insideDialogHeader; the header reserves inline-end space when it contains the button. Without it, the header keeps its normal gutters. Use the unstyledDialogClosewithrenderfor footer actions and custom close controls. A dialog that submits a form cancels user-initiated closes while the submission is pending and closes itself when it succeeds; a failure keeps the dialog open with the draft intact. - Use
AlertDialogonly for a destructive or must-confirm decision requiring an explicit answer. It blocks outside-press dismissal but still closes on Escape; cancel that close inonOpenChangewhen the answer must be explicit.AlertDialogHeaderholds the title and description; anything the user fills in or reviews before answering goes inAlertDialogBody. - Use
Drawerfor side-panel interactions that follow the drawer model. - Use
Menufor button-triggered action lists andContextMenufor context actions. A long action list filters withMenuFilterProvider; choosing a value isComboboxin Selection. UseContextMenuPortal,ContextMenuPositioner, andContextMenuPopupfor custom portal containers or positioning beyondContextMenuContent's common options. - Use
Tooltipfor a supplementary visual label on a control that already has a primary action and an accessible name. UseInfotipwhen the information icon's action is to open the explanation. Text length alone does not determine the component. Follow the Infotip contract for its composition and accessible names. - Use
PreviewCardas a non-interactive enhancement for a link destination. Essential information must also exist without the preview. - Use
Popoverfor explanatory, structured, or interactive content that users must reach on touch or with assistive technology.
Use a real <button type="button"> for button-like triggers. If a Base UI trigger intentionally
renders a non-button element, set nativeButton={false}.