Radix UI Primitives

Overview

Radix UI primitives form the accessible foundation of the documentation interface, wrapping underlying @radix-ui/react-* libraries to provide styled components for custom scrollable viewports, contextual floating popovers, and interactive collapsible or accordion panels. By encapsulating core behavior, these components manage complex UI states such as keyboard navigation, modal focus traps, and smooth CSS animations across search dialogs and navigation menus.

Sources: packages/radix-ui/src/components/dialog/search.tsx:268-296, packages/radix-ui/src/components/ui/scroll-area.tsx:1-17, packages/radix-ui/src/components/ui/popover.tsx:1-30, packages/radix-ui/src/components/ui/accordion.tsx:1-17, packages/radix-ui/src/components/ui/collapsible.tsx:1-34, packages/radix-ui/src/components/ui/navigation-menu.tsx:1-69

Scroll area primitive and viewport scrolling

Component API and DOM Structure

The scroll area primitive wraps @radix-ui/react-scroll-area primitives to construct custom styled viewports and scrollbars across documentation sidebars and scrollable containers. The public exports consist of ScrollArea, ScrollViewport, and ScrollBar, along with helper abstractions such as SidebarViewport that structure vertical lists and page trees with fade masks and containment rules.

Copyexport function ScrollArea({
  className,
  children,
  ...props
}: React.ComponentPropsWithRef<typeof Primitive.Root>) {
  return (
    <Primitive.Root type="scroll" className={cn('overflow-hidden', className)} {...props}>
      {children}
      <Primitive.Corner />
      <ScrollBar orientation="vertical" />
    </Primitive.Root>
  );
}

Sources: packages/radix-ui/src/components/ui/scroll-area.tsx:5-17

The underlying component renders a root container with hidden overflow, automatically appending a corner piece and a vertical scrollbar instance. Inside this structure, ScrollViewport manages the inner scrolling container with full sizing, inherited border radius, and utility modifier classes.

Copyexport function ScrollViewport({
  className,
  children,
  ...props
}: React.ComponentPropsWithRef<typeof Primitive.Viewport>) {
  return (
    <Primitive.Viewport className={cn('size-full rounded-[inherit]', className)} {...props}>
      {children}
    </Primitive.Viewport>
  );
}

Sources: packages/radix-ui/src/components/ui/scroll-area.tsx:19-29

The scrollbar sub-component supports both vertical and horizontal orientations, applying dynamic width or height constraints and fade-out transition animations via data states.

Copyexport function ScrollBar({
  className,
  orientation = 'vertical',
  ...props
}: React.ComponentPropsWithRef<typeof Primitive.Scrollbar>) {
  return (
    <Primitive.Scrollbar
      orientation={orientation}
      className={cn(
        'flex select-none data-[state=hidden]:animate-fd-fade-out',
        orientation === 'vertical' && 'h-full w-1.5',
        orientation === 'horizontal' && 'h-1.5 flex-col',
        className,
      )}
      {...props}
    >
      <Primitive.ScrollAreaThumb className="relative flex-1 rounded-full bg-fd-border" />
    </Primitive.Scrollbar>
  );
}

Sources: packages/radix-ui/src/components/ui/scroll-area.tsx:31-50

Sources: packages/radix-ui/src/components/ui/scroll-area.tsx:1-50

Execution Walkthrough and Component Composition

Sources: packages/radix-ui/src/components/sidebar/base.tsx:185-207, packages/radix-ui/src/layouts/flux/slots/sidebar.tsx:64-81

The rendering pipeline flows through structured sidebar components down to the primitive scrollbar.

1. Sidebar initiates composition by rendering banners, navigation links, and page trees. Sources: packages/radix-ui/src/layouts/flux/slots/sidebar.tsx:64-81
2. SidebarViewport receives the elements and injects them into ScrollArea with flex sizing. Sources: packages/radix-ui/src/components/sidebar/base.tsx:185-207
3. ScrollArea encapsulates the viewport with Primitive.Root, establishing overflow rules and default corner elements. Sources: packages/radix-ui/src/components/ui/scroll-area.tsx:5-17
4. ScrollBar configures orientation (vertical or horizontal) and populates the track with a styled Primitive.ScrollAreaThumb. Sources: packages/radix-ui/src/components/ui/scroll-area.tsx:31-50

Popover primitive for contextual overlays

Component API and Primitives

The popover component architecture builds upon @radix-ui/react-popover primitives, supplying wrapper exports and customized content rendering. The exposed exports map directly to root, trigger, content, and close subcomponents.

Sources: packages/radix-ui/src/components/ui/popover.tsx:1-32

Styling and Content Layout

PopoverContent wraps its elements in PopoverPrimitive.Portal and PopoverPrimitive.Content, applying default alignment and offset settings. The styling uses utility classes for z-index stacking, layout constraints, backdrop filters, and open/closed animations.

CopyclassName={cn(
  'z-50 origin-(--radix-popover-content-transform-origin) overflow-y-auto max-h-(--radix-popover-content-available-height) min-w-[240px] max-w-[98vw] rounded-xl border bg-fd-popover/60 backdrop-blur-lg p-2 text-sm text-fd-popover-foreground shadow-lg focus-visible:outline-none data-[state=closed]:animate-fd-popover-out data-[state=open]:animate-fd-popover-in',
  className,
)}
{...props}

Sources: packages/radix-ui/src/components/ui/popover.tsx:22-26

Collapsible triggers and expandable sections

Primitive Exports and Component API

The collapsible component architecture builds upon @radix-ui/react-collapsible primitives to drive accessible disclosure panels and folder hierarchies within documentation sidebars. The components exported by the wrapper module expose underlying Radix primitives while injecting custom animation classes and mounting states.

Sources: packages/radix-ui/src/components/ui/collapsible.tsx:7-14

Animation and Mounting State

CollapsibleContent manages client-side hydration and enter/exit animations by tracking a local mounted state via useState and useEffect. Once mounted, the component applies conditional keyframe animations (animate-fd-collapsible-up and animate-fd-collapsible-down) governed by the current data-[state] attribute.

Copyexport function CollapsibleContent({
  children,
  ...props
}: React.ComponentPropsWithRef<typeof Primitive.CollapsibleContent>) {
  const [mounted, setMounted] = useState(false);
 
  useEffect(() => {
    setMounted(true);
  }, []);
 
  return (
    <Primitive.CollapsibleContent
      {...props}
      className={cn(
        'overflow-hidden',
        mounted &&
          'data-[state=closed]:animate-fd-collapsible-up data-[state=open]:animate-fd-collapsible-down',
        props.className,
      )}
    >
      {children}
    </Primitive.CollapsibleContent>
  );
}

Sources: packages/radix-ui/src/components/ui/collapsible.tsx:11-34

Accordion wrappers and expandable panels

Component Composition and Primitives

The accordion architecture builds upon @radix-ui/react-accordion primitives to provide multi-item expandable panels with copy-link capabilities, keyboard navigation support, and hash-based anchor integration. The base primitives are re-exported and wrapped across specialized UI files to configure styling, layout, and interaction handlers.

Sources: packages/radix-ui/src/components/ui/accordion.tsx:8-84, packages/radix-ui/src/components/accordion.tsx:11-81

State Management and Hash Navigation

Accordions initializes its state based on the configured type prop, defaulting to 'single' with collapsible behavior enabled. On initial mount, an effect inspects window.location.hash, matches the element ID against the accordion tree, reads its data-accordion-value attribute, and automatically expands the corresponding panel.

Copyexport function Accordions({
  type = 'single',
  ref,
  className,
  defaultValue,
  ...props
}: ComponentProps<typeof Root>) {
  const rootRef = useRef<HTMLDivElement>(null);
  const composedRef = mergeRefs(ref, rootRef);
  const [value, setValue] = useState<string | string[]>(() =>
    type === 'single' ? (defaultValue ?? '') : (defaultValue ?? []),
  );
 
  useEffect(() => {
    const id = window.location.hash.substring(1);
    const element = rootRef.current;
    if (!element || id.length === 0) return;
 
    const selected = document.getElementById(id);
    if (!selected || !element.contains(selected)) return;
    const value = selected.getAttribute('data-accordion-value');
 
    if (value) setValue((prev) => (typeof prev === 'string' ? value : [value, ...prev]));
  }, []);

Sources: packages/radix-ui/src/components/accordion.tsx:18-41

Search dialog modal structure

Search Dialog Modal Structure and Primitives

The search dialog modal architecture relies on @radix-ui/react-dialog primitives alongside specialized components to render accessible modal overlays, dialog content wrappers, animated list containers, and keyboard-navigational list items.

Sources: packages/radix-ui/src/components/dialog/search.tsx:264-417, packages/api-docs/src/components/dialog.tsx:3-17

Keyboard Navigation and Focus Management

SearchDialogList registers a global keydown event listener through an effect event hook (onKey) to capture keyboard navigation events without re-subscribing on every render change. When ArrowDown or ArrowUp events fire, it computes the newly active item identifier based on the current index relative to the total items length, while Enter triggers the selection callback for the active item.

Copyconst onKey = useEffectEvent((e: KeyboardEvent) => {
  if (!items || e.isComposing) return;
 
  if (e.key === 'ArrowDown' || e.key == 'ArrowUp') {
    let idx = items.findIndex((item) => item.id === active);
    if (idx === -1) idx = 0;
    else if (e.key === 'ArrowDown') idx++;
    else idx--;
 
    setActive(items.at(idx % items.length)?.id ?? null);
    e.preventDefault();
  }
 
  if (e.key === 'Enter') {
    const selected = items.find((item) => item.id === active);
 
    if (selected) onSelect(selected);
    e.preventDefault();
  }
});

Sources: packages/radix-ui/src/components/dialog/search.tsx:325-344

Select dropdowns and navigation menus

Select Dropdown Component Architecture

Form selection controls are built on top of @radix-ui/react-select primitives, offering robust keyboard navigation, dropdown portals, scrollable item viewports, and item indicators. The component architecture exposes granular parts including root, group, value, trigger, content, label, item, separator, and scroll buttons.

Sources: packages/api-docs/src/components/select.tsx:6-124, packages/story/src/client/components/select.tsx:7-139

Navigation Menu Integration and Motion Variants

Responsive header navigation utilizes @radix-ui/react-navigation-menu primitives to deliver accessible dropdown panels and menu links. NavigationMenuContent applies absolute positioning, fd-scroll-container scroll handling, a maximum height constraint of 80svh, and motion-driven data attributes for directional entry and exit animations (data-[motion=from-end], data-[motion=from-start], data-[motion=to-end], data-[motion=to-start]).

Copyexport function NavigationMenuContent({
  className,
  ...props
}: React.ComponentPropsWithRef<typeof Primitive.Content>) {
  return (
    <Primitive.Content
      className={cn(
        'absolute inset-x-0 top-0 overflow-auto fd-scroll-container max-h-[80svh] data-[motion=from-end]:animate-fd-enterFromRight data-[motion=from-start]:animate-fd-enterFromLeft data-[motion=to-end]:animate-fd-exitToRight data-[motion=to-start]:animate-fd-exitToLeft',
        className,
      )}
      {...props}
    />
  );
}

Sources: packages/radix-ui/src/components/ui/navigation-menu.tsx:37-50

Related

• Base UI Components
• Shared Layout Architecture