Skip to content

armgit / dify

Public Imported from GitHub
0

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.

6.4 KB
Raw Blame

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 Dialog for modal content that needs focus containment and scroll locking. DialogContent is the centered modal surface: compose DialogHeader, DialogBody and DialogFooter in it, and DialogBody scrolls between the other two. A wrapper between the surface and its parts, such as a form, keeps the flex chain with contents. DialogPopup is the bare dialog element for a surface that places and dresses itself. DialogContent and AlertDialogContent allow transition-none, including state variants, without requiring custom popup composition. DialogHeaderCloseButton is the optional standard close icon inside DialogHeader; the header reserves inline-end space when it contains the button. Without it, the header keeps its normal gutters. Use the unstyled DialogClose with render for 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 AlertDialog only for a destructive or must-confirm decision requiring an explicit answer. It blocks outside-press dismissal but still closes on Escape; cancel that close in onOpenChange when the answer must be explicit. AlertDialogHeader holds the title and description; anything the user fills in or reviews before answering goes in AlertDialogBody.
  • Use Drawer for side-panel interactions that follow the drawer model.
  • Use Menu for button-triggered action lists and ContextMenu for context actions. A long action list filters with MenuFilterProvider; choosing a value is Combobox in Selection. Use ContextMenuPortal, ContextMenuPositioner, and ContextMenuPopup for custom portal containers or positioning beyond ContextMenuContent's common options.
  • Use Tooltip for a supplementary visual label on a control that already has a primary action and an accessible name. Use Infotip when 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 PreviewCard as a non-interactive enhancement for a link destination. Essential information must also exist without the preview.
  • Use Popover for 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}.