Navigation and Container Primitives
Relevant source files
The following files were used as context for generating this wiki page:
Navigation and Container Primitives provide the structural foundation for organizing content and facilitating user movement within the HX-UI framework. These components manage content density, hierarchical visibility, and interactive transitions using a combination of Radix UI primitives and custom styling.
These primitives ensure consistent behavior for complex layout patterns such as tabbed interfaces, expandable sections, and customized scroll behaviors. They prioritize accessibility through ARIA-compliant structures and smooth visual feedback via CSS keyframe animations.
Tabs System
The Tabs primitive organizes content into multiple views that a user can toggle between. It provides two distinct visual variants: underline for primary view switching and pill for toolbars and compact interfaces. The system uses a React Context to synchronize the visual variant between the TabsList and its child TabsTrigger components.
Tabs Architecture and Data Flow
The diagram shows how the TabsVariantContext propagates the chosen style from the list to individual triggers.
| Component | Role | Key Properties |
|---|---|---|
Tabs | Root container | value, onValueChange |
TabsList | Trigger container | variant ("underline" | "pill") |
TabsTrigger | Interactive toggle | value, disabled |
TabsContent | Content panel | value |
Sources: src/primitives/tabs.tsx:14-30, src/primitives/tabs.tsx:64-77
Disclosure Primitives: Accordion and Collapsible
Disclosure primitives manage the visibility of content sections. The Accordion component handles groups of expandable items, while Collapsible manages single instances. Both components utilize CSS keyframe animations (hx-collapse-down and hx-collapse-up) defined in motion.css to ensure smooth height transitions during both expansion and collapse phases.
Accordion State Management
The sequence illustrates the transition lifecycle driven by the data-state attribute.
Sources: src/primitives/accordion.tsx:16-24, src/primitives/collapsible.tsx:6-15
Specialized Container: ScrollArea
The ScrollArea component replaces native browser scrollbars with custom-styled, overlay-style bars. This prevents layout shifts on platforms like Windows or Linux where native scrollbars occupy physical space. The component defaults to a hover type, where scrollbars only appear when the user interacts with the container.
ScrollArea Structure
| Element | Description | Styling Behavior |
|---|---|---|
Viewport | The visible clipping area | size-full rounded-[inherit] |
Scrollbar | The scroll track | transition-colors duration-150 |
Thumb | The draggable handle | bg-border hover:bg-muted-foreground/40 |
Sources: src/primitives/scroll-area.tsx:15-22, src/primitives/scroll-area.tsx:44-54
Overlays and Menus
Navigation is further supported by Drawer and DropdownMenu primitives, which handle temporary contextual content.
Dropdown Menu Flow
DropdownMenu utilizes Radix UI's portal system to ensure the menu renders above other UI layers. It supports sub-menus via DropdownMenuSub and selection states via DropdownMenuRadioItem.
Drawer Directions
The Drawer component, based on vaul, supports four-way directional entry. Styling is dynamically applied based on the data-vaul-drawer-direction attribute.
| Direction | Constraint | Visual Feature |
|---|---|---|
bottom | max-h-[80vh] | Includes a top handle bar |
top | max-h-[80vh] | rounded-b-xl |
left | w-3/4 | rounded-r-xl |
right | w-3/4 | rounded-l-xl |
Sources: src/primitives/dropdown-menu.tsx:18-29, src/primitives/drawer.tsx:49-65
Conclusion
Navigation and Container Primitives in HX-UI prioritize a seamless user experience by combining robust accessibility features with high-performance animations. By abstracting complex behaviors like synchronized tab variants, custom scrollbar management, and multi-directional drawers, these components allow developers to build consistent, professional interfaces without manual state or animation handling.