For AI agents: the complete documentation index is available at /next/llms.txt, the full documentation bundle is available at /next/llms-full.txt, and this page is available as Markdown at /next/ui/components/popover.md.
lynx-ui logo
lynx-ui
  • English
  • Popover

    A headless Popover component for ReactLynx. It provides primitives for positioning and anchor tracking.
    Info

    You can check the source code to understand how it works, and you're welcome to submit PRs to enhance its capabilities.

    Basic Usage

    Examples

    Motion Transitions

    Animate popover content with spring-based entry and tween-based exit transitions.

    Extra Anchor

    If you want to add an extra anchor, you can use the PopoverAnchor Component.

    Cross axis offset adjustment

    Use 'crossAxisOffset' on PopoverPositioner to set the skidding offset of the floating element.

    Structure

    <PopoverRoot>
      <PopoverTrigger />
      <PopoverAnchor />
      <PopoverPositioner>
        <PopoverBackdrop />
        <PopoverContent>
          <PopoverArrow />
        </PopoverContent>
      </PopoverPositioner>
    </PopoverRoot>

    Component API

    PopoverRoot

    The root component of the Popover, containing all of its child components.

    childreniOSAndroidHarmony
    TypeReactNode
    children
    classNameiOSAndroidHarmony
    Typestring
    className
    debugLogiOSAndroidHarmony
    Typeboolean
    Enable debug log for Popover and its sub-components.
    defaultShowiOSAndroidHarmony
    Typeboolean
    Determines whether the dialog should be shown by default. Use this property means the Dialog is uncontrolled.
    forceMountiOSAndroidHarmony
    Typeboolean·Defaultfalse
    Mount the toast and render the content even when it's not shown. At this time, the internal state is "initial".
    onCloseiOSAndroidHarmony
    Type() => void
    Triggered when the popover is closed
    onOpeniOSAndroidHarmony
    Type() => void
    Triggered when the popover is shown
    onVisibleChangeiOSAndroidHarmony
    Type(visible: boolean) => void
    Callback fired when the visibility of the popover changes. This is only called in controlled mode.
    showiOSAndroidHarmony
    Typeboolean
    Determines whether the dialog should be shown. Use this property means the Dialog is controlled. Do not use this props with 'defaultShow'.
    styleiOSAndroidHarmony
    TypeCSSProperties
    style

    PopoverTrigger

    The element that triggers the Popover to show.

    childreniOSAndroidHarmony
    TypeReactNode
    children
    classNameiOSAndroidHarmony
    Typestring
    className
    disabled
    Typeboolean
    Disable this Trigger
    onClickiOSAndroidHarmony
    Type() => void
    Callback function triggered when the component is clicked
    styleiOSAndroidHarmony
    TypeCSSProperties
    style
    transitioniOSAndroidHarmony
    Typeboolean
    When true, className includes transition classes such as 'ui-entering', 'ui-leaving', and 'ui-animating'.

    State-based styling & rendering

    This component exposes runtime states through one or both of the following channels. The table lists only the channels available for each state:

    • UI variant class — when supported, a class like ui-<state> is toggled on the corresponding component node for selectors such as .ui-<state> { ... }.
    • Render-prop field — when supported and children is a function, the state is passed in via children({ <state>: boolean, ... }) for runtime-driven rendering.

    UI variants applied by PopoverTrigger.

    Class NameDescription
    ui-activeApplied while the composed trigger button is pressed and not disabled.
    ui-animatingApplied when `status.animating` is true.
    ui-busyApplied while the popover is entering or leaving.
    ui-closedApplied when `status.closed` is true.
    ui-disabledApplied when the trigger is disabled.
    ui-enteringApplied when `status.entering` is true.
    ui-leavingApplied when `status.leaving` is true.
    ui-openApplied when `status.open` is true.

    PopoverAnchor

    If this component is used, the Popover will use it rather than PopoverTrigger as the real anchor.

    childreniOSAndroidHarmony
    TypeReactNode
    children
    classNameiOSAndroidHarmony
    Typestring
    className
    styleiOSAndroidHarmony
    TypeCSSProperties
    style
    transitioniOSAndroidHarmony
    Typeboolean
    When true, className includes transition classes such as 'ui-entering', 'ui-leaving', and 'ui-animating'.

    UI variants applied by PopoverAnchor.

    Class NameDescription
    ui-animatingApplied when `status.animating` is true.
    ui-closedApplied when `status.closed` is true.
    ui-enteringApplied when `status.entering` is true.
    ui-leavingApplied when `status.leaving` is true.
    ui-openApplied when `status.open` is true.

    PopoverPositioner

    Helps position the Content and Arrow correctly.

    autoAdjustiOSAndroidHarmony
    Typesize | shift
    The auto-adjustment strategy for the popover. Defaults to 'size', which automatically adjusts maxHeight/maxWidth based on the popover size; 'shift' automatically adjusts the position based on the popover width/height.
    classNameiOSAndroidHarmony
    Typestring
    className
    crossAxisOffsetiOSAndroidHarmony
    Typenumber
    Additional crossAxis offset. If this prop is set, the popover will be offset by the specified amount in the crossAxis direction.
    placementiOSAndroidHarmony
    TypePlacement
    The position of the popover. Defaults to 'top'.
    placementOffsetiOSAndroidHarmony
    Typenumber
    The offset of the popover position
    popoverPositionerPropsiOSAndroidHarmony
    TypeViewProps | OverlayProps
    popoverPositioner supports original view props to be directly spread in this prop.
    styleiOSAndroidHarmony
    TypeCSSProperties
    style
    transitioniOSAndroidHarmony
    Typeboolean
    When true, className includes transition classes such as 'ui-entering', 'ui-leaving', and 'ui-animating'.
    childreniOSAndroidHarmony
    TypeReactNode | (status: {open?: boolean, closed?: boolean, leaving?: boolean, entering?: boolean, animating?: boolean}) => ReactNode
    children

    UI variants applied by PopoverPositioner based on its render state.

    Class NameRender PropTypeDescription
    ui-animatinganimatingbooleanThe popper is doing the animations. Takes effect when transition:true. Applied when `status.animating` is true.
    ui-closedclosedbooleanThe popper is closed. If it's force mounted, the initial status will be closed. Applied when `status.closed` is true.
    ui-enteringenteringbooleanThe popper is performing the entering animation. Takes effect when transition:true. Applied when `status.entering` is true.
    ui-leavingleavingbooleanThe popper is performing the leaving animation. Takes effect when transition:true. Applied when `status.leaving` is true.
    ui-openopenbooleanThe popper is opened. Applied when `status.open` is true.

    PopoverBackdrop

    A transparent backdrop that can be used to close the Popover when clicked.

    childreniOSAndroidHarmony
    TypeReactNode
    children
    classNameiOSAndroidHarmony
    Typestring
    className
    onClickiOSAndroidHarmony
    Type() => void
    Callback function triggered when the component is clicked
    styleiOSAndroidHarmony
    TypeCSSProperties
    style
    transitioniOSAndroidHarmony
    Typeboolean
    When true, className includes transition classes such as 'ui-entering', 'ui-leaving', and 'ui-animating'.

    UI variants applied by PopoverBackdrop.

    Class NameDescription
    ui-activeApplied while the composed backdrop button is pressed and not disabled.
    ui-animatingApplied when `status.animating` is true.
    ui-closedApplied when `status.closed` is true.
    ui-disabledApplied while the popover is entering or leaving without motion content.
    ui-enteringApplied when `status.entering` is true.
    ui-leavingApplied when `status.leaving` is true.
    ui-openApplied when `status.open` is true.

    PopoverContent

    The content of the Popover.

    childreniOSAndroidHarmony
    TypeReactNode
    children
    classNameiOSAndroidHarmony
    Typestring
    className
    popoverContentPropsiOSAndroidHarmony
    TypeViewProps
    PopoverContent supports original view props to be directly spread in this prop.
    styleiOSAndroidHarmony
    TypeCSSProperties
    style
    transitioniOSAndroidHarmony
    Typeboolean
    When true, className includes transition classes such as 'ui-entering', 'ui-leaving', and 'ui-animating'.

    UI variants applied by PopoverContent.

    Class NameDescription
    ui-animatingApplied when `status.animating` is true.
    ui-closedApplied when `status.closed` is true.
    ui-enteringApplied when `status.entering` is true.
    ui-leavingApplied when `status.leaving` is true.
    ui-openApplied when `status.open` is true.

    PopoverMotionContent

    Motion-driven content. It owns opacity when an opacity target is specified, and transform when a transform target is specified. It stays mounted until all exit properties complete. Use one motion content per popover root.

    childreniOSAndroidHarmony
    TypeReactNode
    children
    classNameiOSAndroidHarmony
    Typestring
    className
    motioniOSAndroidHarmony
    TypePopoverMotionOptions
    Initial, opening and closing values, with an optional shared transition.
    popoverContentPropsiOSAndroidHarmony
    TypeViewProps
    PopoverContent supports original view props to be directly spread in this prop.
    styleiOSAndroidHarmony
    TypeCSSProperties
    style
    transitioniOSAndroidHarmony
    Typeboolean
    When true, className includes transition classes such as 'ui-entering', 'ui-leaving', and 'ui-animating'.

    UI variants applied by PopoverMotionContent.

    Class NameDescription
    ui-animatingApplied when `status.animating` is true.
    ui-closedApplied when `status.closed` is true.
    ui-enteringApplied when `status.entering` is true.
    ui-leavingApplied when `status.leaving` is true.
    ui-openApplied when `status.open` is true.

    PopoverArrow

    The arrow of the Popover.

    childreniOSAndroidHarmony
    TypeReactNode
    Custom arrow artwork, pointing down before rotation. Its layout size must match size; color only affects the default triangle. Keep PopoverArrow a direct child of PopoverContent so coordinates use the bubble as their origin.
    classNameiOSAndroidHarmony
    Typestring
    className
    coloriOSAndroidHarmony
    Typestring·Default'black'
    The color of the arrow. Defaults to 'black'
    offsetiOSAndroidHarmony
    Typenumber·Default0
    Adjusts the positioning of the arrow along the edge of PopoverContent. For example, this can be used to keep the arrow clear of rounded corners.
    sizeiOSAndroidHarmony
    Typenumber | {height: number, width: number}
    Arrow size. A number retains the square positioning box and protrusion of that size. With custom children, { width, height } describes the original artwork: width is the base and height is the protrusion for every placement. Left/right placements rotate the box automatically. Without children, object sizes retain the default triangle’s legacy behavior using the larger dimension.
    styleiOSAndroidHarmony
    TypeCSSProperties
    style
    transitioniOSAndroidHarmony
    Typeboolean
    When true, className includes transition classes such as 'ui-entering', 'ui-leaving', and 'ui-animating'.

    UI variants applied by PopoverArrow.

    Class NameDescription
    ui-animatingApplied when `status.animating` is true.
    ui-closedApplied when `status.closed` is true.
    ui-enteringApplied when `status.entering` is true.
    ui-leavingApplied when `status.leaving` is true.
    ui-openApplied when `status.open` is true.

    Supporting Types

    PopoverOverlayProps

    The view container of the Popover. Can be overlay or view. Controls the z-index of the popover.

    childreniOSAndroidHarmony
    TypeReactNode | (status: {open?: boolean, closed?: boolean, leaving?: boolean, entering?: boolean, animating?: boolean}) => ReactNode
    children
    classNameiOSAndroidHarmony
    Typestring
    className
    containeriOSAndroidHarmony
    Typestring
    The parent container of the popover overlay
    placementiOSAndroidHarmony
    TypePlacement
    The position of the popover.
    placementOffsetiOSAndroidHarmony
    Typenumber
    The offset of the popover overlay position
    popoverOverlayPropsiOSAndroidHarmony
    TypeViewProps
    PopoverOverlay supports original view props to be directly spread in this prop.
    styleiOSAndroidHarmony
    TypeCSSProperties
    style
    transitioniOSAndroidHarmony
    Typeboolean
    When true, className includes transition classes such as 'ui-entering', 'ui-leaving', and 'ui-animating'.

    PopoverMotionOptions

    Motion targets and their shared default transition.

    closeiOSAndroidHarmony
    TypePopoverMotionTarget
    Target values when closing. Its transition overrides the shared default.
    initialiOSAndroidHarmony
    TypePopoverMotionValues
    Visual values applied on each fresh mount.
    openiOSAndroidHarmony
    TypePopoverMotionTarget
    Target values when opening. Its transition overrides the shared default.
    transitioniOSAndroidHarmony
    TypePopoverMotionTransition
    Default transition for targets without their own transition.

    PopoverMotionValues

    Numeric visual properties supported by PopoverMotionContent.

    opacityiOSAndroidHarmony
    Typenumber
    Opacity.
    rotateiOSAndroidHarmony
    Typenumber
    Rotation in degrees.
    scaleiOSAndroidHarmony
    Typenumber
    Uniform scale.
    scaleXiOSAndroidHarmony
    Typenumber
    Horizontal scale.
    scaleYiOSAndroidHarmony
    Typenumber
    Vertical scale.
    xiOSAndroidHarmony
    Typenumber
    Horizontal translation in logical pixels.
    yiOSAndroidHarmony
    Typenumber
    Vertical translation in logical pixels.

    PopoverMotionTarget

    A visual target and its transition settings.

    opacityiOSAndroidHarmony
    Typenumber
    Opacity.
    rotateiOSAndroidHarmony
    Typenumber
    Rotation in degrees.
    scaleiOSAndroidHarmony
    Typenumber
    Uniform scale.
    scaleXiOSAndroidHarmony
    Typenumber
    Horizontal scale.
    scaleYiOSAndroidHarmony
    Typenumber
    Vertical scale.
    transitioniOSAndroidHarmony
    TypePopoverMotionTransition
    Defaults to a spring with stiffness 300, damping 30 and mass 1.
    xiOSAndroidHarmony
    Typenumber
    Horizontal translation in logical pixels.
    yiOSAndroidHarmony
    Typenumber
    Vertical translation in logical pixels.

    PopoverMotionTransition

    PopoverMotionTransitioniOSAndroidHarmony
    Type({ type: 'spring', stiffness?: number, damping?: number, mass?: number, velocity?: number } | { type: 'tween', duration?: number, ease?: 'linear' | 'easeIn' | 'easeOut' | 'easeInOut' })
    Spring physics or tween timing. Durations are in seconds. A tween defaults to 0.3 seconds and easeOut when its duration or easing is omitted.
    Except as otherwise noted, this work is licensed under a Creative Commons Attribution 4.0 International License, and code samples are licensed under the Apache License 2.0.