> For AI agents: the complete documentation index is available at /next/llms.txt, the full documentation bundle is available at /next/llms-full.txt.

# 

# Popover

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

You can check the [source code](https://github.com/lynx-family/lynx-ui/tree/main/packages/lynx-ui-popover) to understand how it works, and you're welcome to submit PRs to enhance its capabilities.

:::

## Basic Usage


**This is an example below: lynx-ui-popover**

**Entry:** `Basic`
**Bundle:** `dist/PopoverBasic.lynx.bundle` | Web: `dist/PopoverBasic.web.bundle`

```tsx
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from '@lynx-js/react'

import {
  PopoverContent,
  PopoverPositioner,
  PopoverRoot,
  PopoverTrigger,
} from '@lynx-js/lynx-ui'

import { EllipsisIcon, OptionsMenu } from '../shared/index.js'
import './index.css'

function App() {
  return (
    <view className='demo-container lunaris-dark'>
      <PopoverRoot
        defaultShow={true}
        onClose={() => console.info('dismissed!')}
        onOpen={() => console.info('shown!')}
      >
        <PopoverTrigger className='popover-trigger'>
          <EllipsisIcon />
          <PopoverPositioner
            placement='bottom'
            placementOffset={12}
            autoAdjust='shift'
            className='popover-positioner'
          >
            <PopoverContent className='popover-content'>
              <OptionsMenu />
            </PopoverContent>
          </PopoverPositioner>
        </PopoverTrigger>
      </PopoverRoot>
    </view>
  )
}

root.render(<App />)

export default App

```



## Examples

### Motion Transitions

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


**This is an example below: lynx-ui-popover**

**Entry:** `Motion`
**Bundle:** `dist/PopoverMotion.lynx.bundle` | Web: `dist/PopoverMotion.web.bundle`

```tsx {17-18,31-41}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from '@lynx-js/react'

import {
  PopoverArrow,
  PopoverMotionContent,
  PopoverPositioner,
  PopoverRoot,
  PopoverTrigger,
} from '@lynx-js/lynx-ui'

import './index.css'

const spring = { type: 'spring', stiffness: 600, damping: 36 } as const
const exit = { type: 'tween', duration: 0.2, ease: 'easeIn' } as const

function App() {
  return (
    <view className='demo-container lunaris-dark'>
      <PopoverRoot>
        <PopoverTrigger className='popover-trigger'>
          <text className='popover-trigger-text'>?</text>
          <PopoverPositioner
            className='motion-positioner'
            placement='top'
            placementOffset={8}
          >
            <PopoverMotionContent
              className='motion-content'
              motion={{
                initial: { opacity: 0, scale: 0.6 },
                open: { opacity: 1, scale: 1, transition: spring },
                close: { opacity: 0, scale: 0.6, transition: exit },
              }}
            >
              <text className='motion-text'>A little more detail.</text>
              <PopoverArrow size={8} />
            </PopoverMotionContent>
          </PopoverPositioner>
        </PopoverTrigger>
      </PopoverRoot>
    </view>
  )
}

root.render(<App />)

export default App

```



### Extra Anchor

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


**This is an example below: lynx-ui-popover**

**Entry:** `ExtraAnchor`
**Bundle:** `dist/PopoverExtraAnchor.lynx.bundle` | Web: `dist/PopoverExtraAnchor.web.bundle`

```tsx {29}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from '@lynx-js/react'

import {
  PopoverAnchor,
  PopoverContent,
  PopoverPositioner,
  PopoverRoot,
  PopoverTrigger,
} from '@lynx-js/lynx-ui'

import { EllipsisIcon, OptionsMenu } from '../shared/index.js'
import './index.css'

function App() {
  return (
    <view className='demo-container lunaris-dark'>
      <PopoverRoot
        onClose={() => console.info('dismissed!')}
        onOpen={() => console.info('shown!')}
        defaultShow={true}
      >
        <PopoverTrigger className='popover-trigger'>
          <EllipsisIcon />
        </PopoverTrigger>
        <PopoverAnchor className='popover-anchor'>
          <text className='popover-anchor-text'>Anchor</text>
          <PopoverPositioner
            placement='bottom-start'
            placementOffset={12}
            autoAdjust='shift'
            className='popover-positioner'
          >
            <PopoverContent className='popover-content'>
              {
                /* In ExtraAnchor scenario, PopoverContent is not wrapped by PopoverTrigger,
               *  so tap-to-close is not supported. Use a different description accordingly.
               */
              }
              <OptionsMenu description='Only the trigger dismisses this popover. Tapping the anchor or content has no effect.' />
            </PopoverContent>
          </PopoverPositioner>
        </PopoverAnchor>
      </PopoverRoot>
    </view>
  )
}

root.render(<App />)

export default App

```



### Cross axis offset adjustment

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


**This is an example below: lynx-ui-popover**

**Entry:** `OffsetAdjustment`
**Bundle:** `dist/PopoverOffsetAdjustment.lynx.bundle` | Web: `dist/PopoverOffsetAdjustment.web.bundle`

```tsx {29-30}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from '@lynx-js/react'

import {
  PopoverContent,
  PopoverPositioner,
  PopoverRoot,
  PopoverTrigger,
} from '@lynx-js/lynx-ui'

import { EllipsisIcon, OptionsMenu } from '../shared/index.js'
import './index.css'

function App() {
  return (
    <view className='demo-container lunaris-dark'>
      <PopoverRoot
        onClose={() => console.info('dismissed!')}
        onOpen={() => console.info('shown!')}
        defaultShow={true}
      >
        <PopoverTrigger className='popover-trigger'>
          <EllipsisIcon />
          <PopoverPositioner
            placement='bottom'
            placementOffset={12}
            crossAxisOffset={40}
            autoAdjust='shift'
            className='popover-positioner'
          >
            <PopoverContent className='popover-content'>
              <OptionsMenu />
            </PopoverContent>
          </PopoverPositioner>
        </PopoverTrigger>
      </PopoverRoot>
    </view>
  )
}

root.render(<App />)

export default App

```



## Structure

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

## Component API \{#api}

### PopoverRoot \{#api-popover-root}

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


### PopoverTrigger \{#api-popover-trigger}

The element that triggers the Popover to show.



### 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 Name | Description |
| --- | --- |
| Class Nameui-active | DescriptionApplied while the composed trigger button is pressed and not disabled. |
| Class Nameui-animating | DescriptionApplied when `status.animating` is true. |
| Class Nameui-busy | DescriptionApplied while the popover is entering or leaving. |
| Class Nameui-closed | DescriptionApplied when `status.closed` is true. |
| Class Nameui-disabled | DescriptionApplied when the trigger is disabled. |
| Class Nameui-entering | DescriptionApplied when `status.entering` is true. |
| Class Nameui-leaving | DescriptionApplied when `status.leaving` is true. |
| Class Nameui-open | DescriptionApplied when `status.open` is true. |


### PopoverAnchor \{#api-popover-anchor}

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


UI variants applied by PopoverAnchor.


| Class Name | Description |
| --- | --- |
| Class Nameui-animating | DescriptionApplied when `status.animating` is true. |
| Class Nameui-closed | DescriptionApplied when `status.closed` is true. |
| Class Nameui-entering | DescriptionApplied when `status.entering` is true. |
| Class Nameui-leaving | DescriptionApplied when `status.leaving` is true. |
| Class Nameui-open | DescriptionApplied when `status.open` is true. |


### PopoverPositioner \{#api-popover-positioner}

Helps position the Content and Arrow correctly.



UI variants applied by PopoverPositioner based on its render state.


| Class Name | Render Prop | Type | Description |
| --- | --- | --- | --- |
| Class Nameui-animating | Render Prop`animating` | Type`boolean` | DescriptionThe popper is doing the animations. Takes effect when transition:true.
Applied when `status.animating` is true. |
| Class Nameui-closed | Render Prop`closed` | Type`boolean` | DescriptionThe popper is closed.
If it's force mounted, the initial status will be closed.
Applied when `status.closed` is true. |
| Class Nameui-entering | Render Prop`entering` | Type`boolean` | DescriptionThe popper is performing the entering animation. Takes effect when transition:true.
Applied when `status.entering` is true. |
| Class Nameui-leaving | Render Prop`leaving` | Type`boolean` | DescriptionThe popper is performing the leaving animation. Takes effect when transition:true.
Applied when `status.leaving` is true. |
| Class Nameui-open | Render Prop`open` | Type`boolean` | DescriptionThe popper is opened.
Applied when `status.open` is true. |


### PopoverBackdrop \{#api-popover-backdrop}

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


UI variants applied by PopoverBackdrop.


| Class Name | Description |
| --- | --- |
| Class Nameui-active | DescriptionApplied while the composed backdrop button is pressed and not disabled. |
| Class Nameui-animating | DescriptionApplied when `status.animating` is true. |
| Class Nameui-closed | DescriptionApplied when `status.closed` is true. |
| Class Nameui-disabled | DescriptionApplied while the popover is entering or leaving without motion content. |
| Class Nameui-entering | DescriptionApplied when `status.entering` is true. |
| Class Nameui-leaving | DescriptionApplied when `status.leaving` is true. |
| Class Nameui-open | DescriptionApplied when `status.open` is true. |


### PopoverContent \{#api-popover-content}

The content of the Popover.


UI variants applied by PopoverContent.


| Class Name | Description |
| --- | --- |
| Class Nameui-animating | DescriptionApplied when `status.animating` is true. |
| Class Nameui-closed | DescriptionApplied when `status.closed` is true. |
| Class Nameui-entering | DescriptionApplied when `status.entering` is true. |
| Class Nameui-leaving | DescriptionApplied when `status.leaving` is true. |
| Class Nameui-open | DescriptionApplied when `status.open` is true. |


### PopoverMotionContent \{#api-popover-motion-content}

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.


UI variants applied by PopoverMotionContent.


| Class Name | Description |
| --- | --- |
| Class Nameui-animating | DescriptionApplied when `status.animating` is true. |
| Class Nameui-closed | DescriptionApplied when `status.closed` is true. |
| Class Nameui-entering | DescriptionApplied when `status.entering` is true. |
| Class Nameui-leaving | DescriptionApplied when `status.leaving` is true. |
| Class Nameui-open | DescriptionApplied when `status.open` is true. |


### PopoverArrow \{#api-popover-arrow}

The arrow of the Popover.


UI variants applied by PopoverArrow.


| Class Name | Description |
| --- | --- |
| Class Nameui-animating | DescriptionApplied when `status.animating` is true. |
| Class Nameui-closed | DescriptionApplied when `status.closed` is true. |
| Class Nameui-entering | DescriptionApplied when `status.entering` is true. |
| Class Nameui-leaving | DescriptionApplied when `status.leaving` is true. |
| Class Nameui-open | DescriptionApplied when `status.open` is true. |


## Supporting Types \{#api-supporting-types}

### PopoverOverlayProps \{#api-supporting-types-popover-overlay-props}

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


### PopoverMotionOptions \{#api-supporting-types-popover-motion-options}

Motion targets and their shared default transition.


### PopoverMotionValues \{#api-supporting-types-popover-motion-values}

Numeric visual properties supported by PopoverMotionContent.


### PopoverMotionTarget \{#api-supporting-types-popover-motion-target}

A visual target and its transition settings.


### PopoverMotionTransition \{#api-supporting-types-popover-motion-transition}

