Feedback and Overlay Primitives
Relevant source files
The following files were used as context for generating this wiki page:
The Feedback and Overlay Primitives constitute the core interaction layer of the HX-UI library. These components handle temporary user interface states, such as modal dialogs, contextual menus, and status indicators. Built primarily upon radix-ui and vaul, these primitives ensure high accessibility (ARIA compliance) while maintaining a consistent design language.
These components are categorized into two functional groups:
- Overlays: Spatial components that appear over existing content (e.g., Dialog, Drawer, Popover).
- Feedback: Temporal or status-based indicators (e.g., Progress, Skeleton, Tooltip).
Sources: src/index.ts:1-25, README.md:20-35
Overlay Architecture
Overlays in HX-UI follow a Portal-based architecture to ensure they are rendered at the top level of the DOM tree, avoiding z-index or stacking context issues. Components like Dialog, Popover, and DropdownMenu utilize radix-ui primitives to manage focus traps, keyboard navigation, and click-outside behaviors.
Component Relationship Flow
The following diagram illustrates the typical lifecycle and portal rendering of an overlay component (e.g., Dialog).
The diagram shows how DialogPortal detaches the overlay from the local component hierarchy to render it within the document body for proper layering.
Sources: src/primitives/dialog.tsx:43-75, src/primitives/popover.tsx:16-30
Key Overlay Components
| Component | Base Library | Primary Use Case | Key Prop/Behavior |
|---|---|---|---|
| Dialog | radix-ui | Modal interactions requiring focus. | showCloseButton: toggles built-in close icon. |
| Drawer | vaul | Mobile-friendly slide-in panels. | Supports bottom, left, right, and top directions. |
| Popover | radix-ui | Contextual floating content. | sideOffset: default 4px gap from trigger. |
| DropdownMenu | radix-ui | List of actions or selectable items. | Supports sub-menus and radio groups. |
Sources: src/primitives/dialog.tsx:1-10, src/primitives/drawer.tsx:1-10, src/primitives/popover.tsx:1-10, src/primitives/dropdown-menu.tsx:1-10
Feedback and Status Systems
Feedback primitives provide visual cues regarding system processes or element descriptions.
Progress Indicators
The Progress component uses the aria-valuenow attribute for accessibility and leverages CSS transforms for performance. Using transforms ensures that high-frequency updates (like file upload progress) occur on the compositor thread rather than triggering expensive layout repaints.
The diagram outlines the composition of ProgressMeter and the conditional logic for the visual indicator.
Sources: src/primitives/progress.tsx:14-35, src/primitives/progress.tsx:75-90
Tooltips and Hints
Tooltips are designed for minimal visual weight. Unlike Popovers, Tooltips in HX-UI use an inverted color scheme (background-foreground contrast) to differentiate them as temporary labels.
- TooltipHint: A convenience wrapper that includes a
TooltipProvider. It prevents the common error where developers forget to wrap tooltips in a provider, which causes the application to crash in Radix UI. - Performance: The default
delayDurationis set to0msto provide instant feedback for icon-only buttons.
Sources: src/primitives/tooltip.tsx:15-25, src/primitives/tooltip.tsx:65-85
Implementation Details
Dialog and Drawer Configuration
Dialogs use a fixed max-width calculation: max-w-[min(24rem,calc(100%-2rem))]. This ensures the dialog remains responsive on small screens while maintaining a consistent size on larger displays. The DialogContent component explicitly prevents auto-focus on open via onOpenAutoFocus={(e) => e.preventDefault()} to allow for custom initial focus management.
Drawers utilize the vaul library to handle touch gestures and dragging. They include a visual "handle" (a rounded-full div) that only appears when the drawer is positioned at the bottom.
Sources: src/primitives/dialog.tsx:55-65, src/primitives/drawer.tsx:55-65
Progress Tone and Values
The Progress component supports specific semantic tones:
const toneClass = {
primary: "bg-primary",
success: "bg-emerald-500",
warning: "bg-amber-500",
destructive: "bg-destructive",
}[tone];
Sources: src/primitives/progress.tsx:30-36
Skeleton Loading
The Skeleton primitive provides a placeholder for loading states. It is often paired with SkeletonText to simulate typography.
Sources: src/primitives/skeleton.tsx:1-20
Summary
The Feedback and Overlay Primitives are the primary mechanisms for handling user attention and process transparency in HX-UI. By wrapping complex accessibility logic from Radix UI and Vaul, these primitives allow developers to implement sophisticated modal interactions and progress tracking with minimal boilerplate. All components respect the design tokens defined in tokens.css, ensuring that changes to variables like --radius or --primary propagate through all overlays and feedback elements.
Sources: README.md:15-30, src/index.ts:10-40