---
title: Popover
path: component/popover
group: Basics
---
## Popover
Common trigger pop widget, you can customize postion、trigger method、display style.
The widget supports nested pop
**The widget do not support style, if you need bubble-like tips component, please use `Pop`.**
### Guides
* If `Pop` widget do not meet your needs, you can achieve custom trigger pop by using `Popover`
* Can be used as `Dropdown`
### API
| Property | Description | Type | Default | Alternative |
|------|------|------|--------|--------|
| position | position way, refer to `Popover.Positon` | Positon | | |
| cushion | optional, position offset, generally it reserves a space for some icon like array | number | `0` | |
| display | optional, the display property specifies the type of box used for an HTML element. | string | `'block'` | all legal `display` value in CSS |
| onShow | optional, the callback after pop shows| func | `noop` | |
| onClose | optional, the callback after pop closes | func | `noop` | |
| onBeforeShow | optional, the callback before pop opens, only triggered by user's operation, setting `visible` outside will not call | func | `noop` | |
| onBeforeClose | optional, the callback after pop closes, only triggered by user's operation, setting `visible` outside will not call | `noop` | |
| containerSelector | optional, pop's parent node CSS selector | string | `'body'` | all legal CSS selector |
| visible | optional, manual control pop's show or hide, must be used with `onVisibleChange` | bool | | |
| onVisibleChange | optional, the callback when manual control, must be used with `visible`, only triggered by user's open/close operation | func | | |
| className | optional, custom extra class name | string | `''` | |
| wrapperClassName | optional, trigger outerline div classname | string | `''` | |
| width | optional, width | string or number | | |
| prefix | optional, custom prefix | string | `'zent'` | |
`onBeforeShow` and `onBeforeClose` will return a `Promise`，`Popover` will open/close after `Promise` resolve，if `Promise` reject, open/close opreation will stop.
If you do not use `Promise`, `onBeforeShow` and `onBeforeClose` also supports two arguments `callback` and `escapse`, you have to manual call `callback` to open/close in `onBeforeShow` and `onBeforeClose`. manual call `escape` to stop open/close opreation.
`onBeforeShow(callback: ?function, escape: ?escape): ?Promise`
Every kinds of trigger has it's own API to control component behavior, custom trigger can specifies it's parameter.
#### Trigger.Click
| Property | Description | Type | Default |
| --------- | ------------------------------------------------ | -------------------- | ------------- |
| autoClose | optional, whether to auto close pop when click `outside` | bool | `true` |
| isOutside | optional, to determine a node is `outside` or not, click outside to close pop. default trigger and the node outside pop is `outside` | func: (node, data) => bool | `() => false` |
The `data` in isOutside includes two attributes ：`contentNode` and `triggerNode`。
#### Trigger.Hover
| Property | Description | Type | Default |
| --------- | ---------------------------------------- | -------------------- | ------------- |
| showDelay | optional, the duration before layer open (in milliseconds), during this time, if you move mouse out of layer, pop will not open | number | `150` |
| hideDelay | optional, the duration before layer close (in milliseconds), during this time, if you move mouse out of layer, pop will not close | number | `150` |
| isOutside | optional,to determine a node is `outside` or not. default trigger and the node outside pop is `outside` | func: (node, data) => bool | |
| quirk | optional，quirk mode，in this mode, mouse is not required to move out trigger and layer when close triggers | bool | `false` |
The `data` in isOutside includes two attributes：`contentNode` 和 `triggerNode`。
#### Trigger.Focus
Display when it gets focus， close when it loses focus, no params
#### Trigger.Base
All trigger's base class, implement custom trigger need to inherit this class, you have rewrite `getTriggerProps` method to add trigger event. and you can control pop's open/close in event handle function.
| Property | Description | Type |
| ------------------ | ------------------------------------------------ | ---------------------- |
| getTriggerNode | get trigger's DOM node | func: () => node |
| getContentNode | get pop's DOM node | func: () => node |
| open | open pop | func |
| close | close pop | func |
| contentVisible | whether ccurent pop is opened or not | bool |
| onTriggerRefChange | when ref changes, callback is executed. and it is only needs when you rewrite render function | func:(instance) |
### Position API
Position is used to position layer. there is 12 kinds of basic positions. and you can add custom position algorithm. the `cushion` on Popover affect position. it usually provides offset.
```
TopLeft TopCenter TopRight
LeftTop RightTop
LeftCenter RightCenter
LeftBottom RightBottom
BottomLeft BottomCenter BottomRight
```
Except for 12 kinds of basic position algorithm, there is 6 position algorithm to automatically determine appropriate position according to the left space in screen: `AutoBottomLeft`，`AutoBottomCenter`, `AutoBottomRight`, `AutoTopLeft`, `AutoTopCenter` and `AutoTopRight`. those algorithm is used for dropdown widget。
Every object in position algorithm has a `locate` function which can be used to implement a combination of positioning algorithms.
```jsx
Popover.Position.create((anchorBoundingBox, containerBoundingBox, contentDimension, options) => {
if (someCondition) {
return Popover.Position.BottomLeft.locate(anchorBoundingBox, containerBoundingBox, contentDimension, options);
}
return Popover.Position.TopRight.locate(anchorBoundingBox, containerBoundingBox, contentDimension, options);
});
```
#### Position.create
The factory function, receiving a function as parameter, is used to customize position
```jsx
// a bounding box is an object with these fields: {top, left, right, bottom, width, height}
const position = Popover.Position.create((anchorBoundingBox, containerBoundingBox, contentDimension, options) => {
return {
getCSSStyle() {
return {
position: 'fixed',
left: 0,
top: 0,
opacity: 0
};
},
name: 'position-example'
};
});
```
Anchor means trigger，container is nearst layer's parent node which have it's own position.
`anchorBoundingBox` and `containerBoundingBox` is relative to container's upper-left corner.
`contentDimension` is layer's width and height.
`options` contains another useful arguments:
* `options.cushion` position offset passed by Props
* `options.anchor` anchor's DOM node
* `options.container` container's DOM node
* `options.anchorBoundingBoxViewport` anchor is a coordinate relative to viewport
* `options.containerBoundingBoxViewport` container is a coordinate relative to viewport
#### withPopover high-level component
The high-level component provides some important functions. it can be used to manually close pop in `Content`
| Property | Description | Type |
| -------------- | --------------------- | ---------------- |
| getTriggerNode | get trigger's DOM node | func: () => node |
| getContentNode | get layer's DOM node | func: () => node |
| open | open layer | func |
| close | close layer | func |
Example：
```jsx
// click close button to close layer
const HoverContent = withPopover(function HoverContent({ popover }) {
return (