Positioning

After positioning, Radix writes the actual data-side and data-align (also after a flip) on the surface, and provides the CSS variables --radix-popover-content-available-height, --radix-popover-trigger-width… (the prefix depends on the component: tooltip, dropdown-menu, select, hover-card).

{/* Leave room for a 74px top bar and a 16px margin on the other edges */}
<PopoverSurface
  side="bottom"
  align="start"
  collisionPadding={{ top: 80, right: 16, bottom: 16, left: 16 }}
  className="max-h-(--radix-popover-content-available-height) overflow-y-auto data-[side=top]:origin-bottom"
>
  …
</PopoverSurface>

{/* Stay on the chosen side and accept clipping (rarely needed) */}
<MenuPopover avoidCollisions={false}>…</MenuPopover>

• Radix does not know about your sticky header. Set collisionPadding on that side so the surface does not slide under it.
• Long lists: cap the height with the --radix-*-content-available-height variable and let the list scroll, instead of letting the surface grow taller than the viewport (Dropdown already does this).
• Animations by direction: style with data-[side=top]:…, because the actual side can differ from the one you picked.

<YugenProvider theme="dark" brand="web" className="p-4">
  <Popover>
    <PopoverTrigger asChild>
      <Button appearance="primary">Open popover</Button>
    </PopoverTrigger>
    {/* Picks up the dark theme and Web brand of the nested provider, even though it renders into <body> */}
    <PopoverSurface withArrow>Dark background, Web brand.</PopoverSurface>
  </Popover>
</YugenProvider>

// Writing a new portal surface? Spread the props of the nearest provider:
import { usePortalThemeProps } from "@/components/ui";

function MyFloatingSurface(props) {
  const portalTheme = usePortalThemeProps(); // {} under the root provider
  return <SomePrimitive.Portal><SomePrimitive.Content {...portalTheme} {...props} /></SomePrimitive.Portal>;
}

• App-wide theme: use <YugenProvider applyToDocument> at the root. The attributes sit on <html>, so every portal gets them.
• Nested theme: every Yugen floating surface (PopoverSurface, MenuPopover, TooltipContent, HoverCardContent, DialogSurface, DrawerSurface, ContextMenu, Menubar, the Dropdown / Combobox / TagPicker listbox) sets the nested provider's data-theme / data-brand / dir through the usePortalThemeProps() hook. Call this hook in surfaces you write yourself.
• Text direction needs no extra work: floating surfaces (PopoverSurface, TooltipContent, HoverCardContent, DialogSurface, DrawerSurface, menus and listboxes) set the dir of the nearest provider, because React context (including DirectionProvider) passes through portals.

// The whole app: keep the scrollbar while Menu, ContextMenu or Dropdown is open
<YugenProvider applyToDocument scrollLock="keep-scrollbar">
  <App />
</YugenProvider>

// Without the provider: set the attribute on <html>
<html data-yugen-scroll-lock="keep-scrollbar">

// One menu that doesn't lock scrolling
<Menu modal={false}>…</Menu>

• scrollLock="keep-scrollbar" on the root provider writes data-yugen-scroll-lock to <html>: the scrollbar stays and nothing shifts, but wheel and touch scrolling outside the surface are still blocked. Apps without the provider set the attribute themselves. The default is "hide-scrollbar" for now; 1.0 switches it to "keep-scrollbar".
• modal={false} on Menu or ContextMenu: the page keeps scrolling, outside clicks reach the page right away, and the rest of the page is not hidden from screen readers. Good for menus opened from a toolbar inside long content.
• Elements with position: fixed at the right edge (headers, floating buttons) shift by the scrollbar width when the scrollbar hides, unless they have the right-scroll-bar-position class (or width-before-scroll-bar for full-width elements). With keep-scrollbar they don't need it.