rc-trigger

rc-trigger (published as @rc-component/trigger) is a headless React primitive for showing a popup relative to a trigger element, handling the hard parts of positioning: viewport-aware alignment, automatic flipping/shifting when a popup would overflow the screen, portal rendering, animation hooks, and interaction modes (hover, click, focus, context menu). It is not a visual component itself — it renders whatever popup content you give it, positioned correctly.

Originally published as rc-trigger and now maintained under the @rc-component scope, it is the foundational positioning engine behind Ant Design’s Dropdown, Tooltip, Popover, Select, and Cascader components, making it one of the most widely-depended-on low-level UI primitives in the React ecosystem despite being invisible to most application developers.

What You Get

• A Trigger component that positions arbitrary popup content relative to a trigger element
• Configurable alignment (builtinPlacements) with automatic flip/shift when the popup would overflow the viewport
• Multiple interaction modes: hover, click, focus, and context-menu triggered popups, independently for show and hide
• Portal-based rendering so popups escape overflow/clipping containers, plus support for rendering inside Shadow DOM
• Animation/motion hooks for enter/leave transitions and an arrow option for pointer indicators
• A mask option for click-outside-to-close backdrop behavior

Common Use Cases

• Building custom dropdown, tooltip, or popover components with precise, viewport-aware positioning
• Powering component libraries that need a shared, battle-tested popup engine instead of reimplementing positioning logic
• Implementing context menus or hover cards that must reposition themselves near screen edges
• Rendering popups correctly inside Shadow DOM or portal-heavy applications

Under The Hood

Architecture - The core Trigger component (src/index.tsx) manages open/close state and interaction event wiring (hover/click/focus/contextmenu handlers), delegating actual DOM measurement and placement math to a Popup subcomponent (src/Popup/) and a set of hooks (src/hooks/) that recompute alignment on resize/scroll. A UniqueProvider context ensures only one popup instance is active at a time when multiple triggers share overlapping regions, and context.ts propagates trigger-level configuration down to nested popup content without prop drilling.

Tech Stack - TypeScript + React, built with father (a React component build tool) producing both ES module and CommonJS outputs, with Less for the small amount of positioning-related CSS in assets/. Documentation site is built with dumi. Tests run on Jest (rc-test) with coverage tracked via nyc.

Code Quality - The tests/ directory is extensive and scenario-driven — dedicated suites for flip behavior, flip+shift combinations, mobile viewports, Shadow DOM rendering, portals, masks, arrows, unique-instance behavior, and raw performance, reflecting how many edge cases real-world popup positioning must handle. As the shared foundation for Ant Design’s interactive components, the codebase is held to a high bar for regression safety given how many downstream components depend on its exact positioning behavior.

API Design - The API centers on a single Trigger component taking popup, action, popupPlacement, and builtinPlacements props, which is flexible but has real depth (placement configuration objects, points, offsets) that a developer needs to learn to fully customize behavior — this is a low-level primitive, not a plug-and-play tooltip component, so it trades some initial learning curve for maximum positioning control.