Popup
<zn-popup> | ZnPopup
Short summary of the component’s intended use.
<zn-popup></zn-popup>
Examples
First Example
TODO
Second Example
TODO
Importing
If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.
To import this component from the CDN using a script tag:
<script type="module" src="https://cdn.jsdelivr.net/npm/@kubex/zinc@1.0.0/dist/components/popup/popup.js"></script>
To import this component from the CDN using a JavaScript import:
import 'https://cdn.jsdelivr.net/npm/@kubex/zinc@1.0.0/dist/components/popup/popup.js';
To import this component using a bundler:
import '@kubex/zinc/dist/components/popup/popup.js';
Slots
| Name | Description |
|---|---|
| (default) | The default slot. |
example
|
An example slot. |
Learn more about using slots.
Properties
| Name | Description | Reflects | Type | Default |
|---|---|---|---|---|
popup
|
A reference to the internal popup container. Useful for animating and styling the popup with JavaScript. |
HTMLElement
|
- | |
anchor
|
The element the popup will be anchored to. If the anchor lives outside of the popup, you can provide
the anchor element id, a DOM element reference, or a VirtualElement. If
the anchor lives inside the popup, use the anchor slot instead.
|
Element | string | VirtualElement
|
- | |
active
|
Activates the positioning logic and shows the popup. When this attribute is removed, the positioning logic is torn down and the popup will be hidden. |
|
boolean
|
false
|
placement
|
The preferred placement of the popup. Note that the actual placement will vary as configured to keep the panel inside of the viewport. |
|
'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'right' |
'right-start' | 'right-end' | 'left' | 'left-start' | 'left-end'
|
'top'
|
strategy
|
Determines how the popup is positioned. The absolute strategy works well in most cases,
but if overflow is clipped, using a fixed position strategy can often workaround it.
|
|
'absolute' | 'fixed'
|
'fixed'
|
distance
|
The distance in pixels from which to offset the panel away from its anchor. |
number
|
0
|
|
skidding
|
The distance in pixels from which to offset the panel along its anchor. |
number
|
0
|
|
arrow
|
Attaches an arrow to the popup. The arrow’s size and color can be customized using the
--arrow-size and --arrow-color custom properties. For additional
customizations, you can also target the arrow using ::part(arrow) in your stylesheet.
|
boolean
|
false
|
|
arrowPlacement
arrow-placement
|
The placement of the arrow. The default is anchor, which will align the arrow as close
to the center of the anchor as possible, considering available space and arrow-padding.
A value of start, end, or center will align the arrow to the
start, end, or center of the popover instead.
|
'start' | 'end' | 'center' | 'anchor'
|
'anchor'
|
|
arrowPadding
arrow-padding
|
The amount of padding between the arrow and the edges of the popup. If the popup has a border-radius, for example, this will prevent it from overflowing the corners. |
number
|
10
|
|
flip
|
When set, placement of the popup will flip to the opposite site to keep it in view. You can use
flipFallbackPlacements to further configure how the fallback placement is determined.
|
boolean
|
false
|
|
flipFallbackPlacements
flip-fallback-placements
|
If the preferred placement doesn’t fit, popup will be tested in these fallback placements until one fits. Must be a string of any number of placements separated by a space, e.g. “top bottom left”. If no placement fits, the flip fallback strategy will be used instead. |
string
|
''
|
|
flipFallbackStrategy
flip-fallback-strategy
|
When neither the preferred placement nor the fallback placements fit, this value will be used to determine whether the popup should be positioned using the best available fit based on available space or as it was initially preferred. |
'best-fit' | 'initial'
|
'best-fit'
|
|
flipBoundary
|
The flip boundary describes clipping element(s) that overflow will be checked relative to when flipping. By default, the boundary includes overflow ancestors that will cause the element to be clipped. If needed, you can change the boundary by passing a reference to one or more elements to this property. |
Element | Element[]
|
- | |
flipPadding
flip-padding
|
The amount of padding, in pixels, to exceed before the flip behavior will occur. |
number
|
0
|
|
shift
|
Moves the popup along the axis to keep it in view when clipped. |
boolean
|
false
|
|
shiftBoundary
|
The shift boundary describes clipping element(s) that overflow will be checked relative to when shifting. By default, the boundary includes overflow ancestors that will cause the element to be clipped. If needed, you can change the boundary by passing a reference to one or more elements to this property. |
Element | Element[]
|
- | |
shiftPadding
shift-padding
|
The amount of padding, in pixels, to exceed before the shift behavior will occur. |
number
|
0
|
|
autoSize
auto-size
|
When set, this will cause the popup to automatically resize itself to prevent it from overflowing. |
'horizontal' | 'vertical' | 'both'
|
- | |
sync
|
Syncs the popup’s width or height to that of the anchor element. |
'width' | 'height' | 'both'
|
- | |
autoSizeBoundary
|
The auto-size boundary describes clipping element(s) that overflow will be checked relative to when resizing. By default, the boundary includes overflow ancestors that will cause the element to be clipped. If needed, you can change the boundary by passing a reference to one or more elements to this property. |
Element | Element[]
|
- | |
autoSizePadding
auto-size-padding
|
The amount of padding, in pixels, to exceed before the auto-size behavior will occur. |
number
|
0
|
|
hoverBridge
hover-bridge
|
When a gap exists between the anchor and the popup element, this option will add a “hover bridge”
that fills the gap using an invisible element. This makes listening for events such as
mouseenter and mouseleave more sane because the pointer never technically
leaves the element. The hover bridge will only be drawn when the popover is active.
|
boolean
|
false
|
|
updateComplete |
A read-only promise that resolves when the component has finished updating. |
Learn more about attributes and properties.
Events
| Name | React Event | Description | Event Detail |
|---|---|---|---|
zn-event-name |
|
Emitted as an example. | - |
Learn more about events.
Methods
| Name | Description | Arguments |
|---|---|---|
reposition() |
Forces the popup to recalculate and reposition itself. | - |
Learn more about methods.
Custom Properties
| Name | Description | Default |
|---|---|---|
--example |
An example CSS custom property. |
Learn more about customizing CSS custom properties.
Parts
| Name | Description |
|---|---|
base |
The component’s base wrapper. |
Learn more about customizing CSS parts.
Dependencies
This component automatically imports the following dependencies.
<zn-example>