The Placer Toolkit alpha has
arrived! 🎉
Plenty of changes are coming your
way—some big, some breaking, some
even nuclear! Beware the changelog…
Popup
<pc-popup> Popup is a utility that lets you declaratively anchor “popup” containers to another element.
This component’s name is inspired by <popup>. It uses Floating UI under the hood to provide a well‐tested, lightweight and fully declarative positioning utility for tooltips, dropdowns and more.
Popup doesn’t provide any styles—just positioning! The popup’s preferred placement, distance and skidding (offset) can be configured using attributes. An arrow that points to the anchor can be shown and customised to your liking. Additional positioning options are available and described in more detail below.
Popup is a low‐level utility built specifically for positioning elements. Do not mistake it for a tooltip or similar because it does not facilitate an accessible experience! Almost every correct usage of it will involve building other components. It should rarely, if ever, occur directly in your HTML.
<div class="popup-overview">
<pc-popup placement="top" active>
<span slot="anchor"></span>
<div class="box"></div>
</pc-popup>
<div class="popup-overview-options">
<pc-select
class="popup-overview-select"
label="Placement"
name="placement"
value="top"
>
<pc-option value="top">top</pc-option>
<pc-option value="top-start">top-start</pc-option>
<pc-option value="top-end">top-end</pc-option>
<pc-option value="bottom">bottom</pc-option>
<pc-option value="bottom-start">bottom-start</pc-option>
<pc-option value="bottom-end">bottom-end</pc-option>
<pc-option value="right">right</pc-option>
<pc-option value="right-start">right-start</pc-option>
<pc-option value="right-end">right-end</pc-option>
<pc-option value="left">left</pc-option>
<pc-option value="left-start">left-start</pc-option>
<pc-option value="left-end">left-end</pc-option>
</pc-select>
<pc-input
label="Distance"
type="number"
name="distance"
value="0"
></pc-input>
<pc-input
label="Skidding"
type="number"
name="skidding"
value="0"
></pc-input>
</div>
<div class="popup-overview-options">
<pc-switch name="active" checked>Active</pc-switch>
<pc-switch name="arrow">Arrow</pc-switch>
</div>
</div>
<script>
const container = document.querySelector(".popup-overview");
const popup = container.querySelector("pc-popup");
const select = container.querySelector('pc-select[name="placement"]');
const distance = container.querySelector('pc-input[name="distance"]');
const skidding = container.querySelector('pc-input[name="skidding"]');
const active = container.querySelector('pc-switch[name="active"]');
const arrow = container.querySelector('pc-switch[name="arrow"]');
select.addEventListener("pc-change", () => (popup.placement = select.value));
distance.addEventListener("pc-input", () => (popup.distance = distance.value));
skidding.addEventListener("pc-input", () => (popup.skidding = skidding.value));
active.addEventListener("pc-change", () => (popup.active = active.checked));
arrow.addEventListener("pc-change", () => (popup.arrow = arrow.checked));
</script>
<style>
.popup-overview pc-popup {
--arrow-color: var(--pc-color-primary-fill-loud);
}
.popup-overview span[slot="anchor"] {
display: inline-block;
margin: var(--pc-spacing-xxxxl);
inline-size: 150px;
block-size: 150px;
border: var(--pc-border-width-m) dashed
var(--pc-color-neutral-border-normal);
border-radius: var(--pc-border-radius-l);
}
.popup-overview .box {
inline-size: 100px;
block-size: 55px;
background-color: var(--pc-color-primary-fill-loud);
border-radius: var(--pc-border-radius-m);
}
.popup-overview-options {
display: flex;
align-items: center;
justify-content: flex-start;
flex-wrap: wrap;
gap: var(--pc-spacing-s);
}
.popup-overview-options pc-select {
inline-size: 200px;
}
.popup-overview-options pc-input {
inline-size: 100px;
}
.popup-overview-options + .popup-overview-options {
margin-block-start: var(--pc-spacing-m);
}
</style>A popup’s anchor should not be styled with display: contents since the coordinates will not be eligible for calculation. However, if the anchor is a <slot> element, the Popup component will use the first assigned element as the anchor. This behaviour allows other components to pass anchors through more easily via composition.
Demos#
Activation#
Popups are inactive and hidden until the active attribute is applied. Removing the attribute will tear down all positioning logic and event listeners, meaning you can have many idle popups on the page without affecting performance.
External anchors#
By default, anchors are slotted into the popup using the anchor slot. If your anchor needs to live outside of the popup, you can pass the anchor’s id to the anchor attribute. Alternatively, you can pass an element reference to the anchor property to achieve the same effect without using an id.
Placement#
Use the placement attribute to tell the popup the preferred placement of the popup. The actual position will vary to ensure the panel remains in the viewport if you’re using positioning features like flip or shift.
Since placement is preferred when using flip, you can observe the popup’s current placement when it’s active by looking at the data-current-placement attribute. This attribute will update as the popup flips to find available space and will be removed when the popup is deactivated.
Distance#
Use the distance attribute to change the distance between the popup and its anchor. A positive value will move the popup further away and a negative value will move it closer to the anchor.
Skidding#
The skidding attribute is similar to distance, but instead allows you to offset the popup along the anchor’s axis. Both positive and negative values are allowed.
Arrows#
Add an arrow to your popup with the arrow attribute. It’s usually a good idea to set a distance to make room for the arrow. To adjust the arrow’s colour and size, use the --arrow-color and --arrow-size custom properties, respectively. You can also target the arrow part to add additional styles such as shadows and borders.
By default, the arrow will be aligned as close to the centre of the anchor as possible, considering available space and arrow-padding. You can the arrow-placement attribute to force the arrow to align to the start, centre or end of the popup instead.
Syncing with the anchor’s dimensions#
Use the sync attribute to make the popup the same with or height as the anchor element. This is useful for controls that need the popup to stay the same width or height as the anchor element.
Flip#
When the popup doesn’t have enough room in its preferred placement, it can automatically flip to keep it in view. To enable this, use the flip attribute. By default, the popup will flip to the opposite placement, but you can configure preferred fallback placements using flip-fallback-placement and flip-fallback-strategy. Additional options are available to control the flip behaviour’s boundary and padding.
Scroll the container to see how the popup flips to prevent clipping.
Flip fallbacks#
While using the flip attribute, you can customise the placement of the popup when the preferred placement doesn’t have room. For this, use flip-fallback-placements and flip-fallback-strategy.
If the preferred placement doesn’t have room, the first suitable placement found in flip-fallback-placement will be used. The value of this attribute must be a string including any number of placements separated by a space, like "right bottom".
If no fallback placement works, the final placement will be determined by flip-fallback-strategy. This value can be either initial (default), where the placement reverts to the position in placement, or best-fit, where the placement is chosen based on available space.
Scroll the container to see how the popup changes its fallback placement to prevent clipping.
Shift#
When a popup is longer than its anchor, it risks being clipped by an overflowing container. In this case, use the shift attribute to shift the popup along its axis and back into view. You can customise the shift behaviour using shiftBoundary and shift-padding.
Toggle the switch to see the demo in action.
Auto‐size#
Use the auto-size attribute to tell the popup to resize when necessary to prevent it from getting clipped. Possible values are horizontal, vertical and both. You can use autoSizeBoundary and auto-size-padding to customise the behaviour of this option. Auto‐size works well with flip, but if you’re using auto-size-padding, make sure flip-padding is the same value.
When using auto-size, one or both of --auto-size-available-width and --auto-size-available-height will be applied to the host element. These values determine the available space the popover has before clipping will occur. Since they cascade, you can use them to set a maximum width/height on your popup’s content and easily control its overflow.
Scroll the container to see the popup resize as its available space changes.
Hover bridge#
When a gap exists between the anchor and the popup, this option will add a “hover bridge” that fills the gap using an invisible element. This makes listening for events such as mouseover and mouseout more sane because the cursor technically never leaves the element. The hover bridge will only be drawn when the popup is active. For demo purposes, the hover bridge will be shown in a transparent blue colour.
Virtual elements#
In most cases, popups are anchored to an actual element. Sometimes, it can be useful to anchor them to non‐DOM elements. To do this, you can pass a VirtualElement to the anchor property. A virtual element must contain a function called getBoundingClientRect() that returns a DOMRect object as shown below.
const virtualElement = {
getBoundingClientRect() {
// …
return { width, height, x, y, top, left, right, bottom };
},
};This demo anchors a popup to the mouse cursor using a virtual element. As such, a mouse is required to properly view it.
Sometimes, the getBoundingClientRects might be derived from a real element. In this case, provide the anchor element as context to ensure clipping and position updates for the popup work well.
const virtualElement = {
getBoundingClientRect() {
// …
return { width, height, x, y, top, left, right, bottom };
},
contextElement: anchorElement,
};Properties#
| Name | Description | Reflects | Default |
|---|---|---|---|
anchor | The element the popup will be anchored to. If the anchor lives outside of the popup, you can provide the anchor element’s id, a DOM element reference or a VirtualElement. If the anchor lives inside the popup, use the anchor slot instead.Type: Element | string | VirtualElement | undefined |
| ‐ |
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. Type: 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. Type: "top"
| "top-start"
| "top-end"
| "bottom"
| "bottom-start"
| "bottom-end"
| "right"
| "right-start"
| "right-end"
| "left"
| "left-start"
| "left-end" |
| "top" |
boundary | The bounding box to use for flipping, shifting and auto‐sizing. Type: "viewport" | "scroll" |
| "viewport" |
distance | The distance in pixels from which to offset the panel away from its anchor. Type: number |
| 0 |
skidding | The distance in pixels from which to offset the panel alongside its anchor. Type: number |
| 0 |
arrow | Adds an arrow to the popup. The arrow’s size and colour can be customised using the --arrow-size and --arrow-color custom properties. For additional customisation, you can also target the arrow using the arrow part in your stylesheet.Type: boolean |
| false |
arrowPlacementarrow-placement | The placement of the arrow. The default is anchor, which will align the arrow as close to the centre of the anchor as possible, considering available space and arrow padding. The alignment values will align the arrow to the popup instead.Type: "start"
| "end"
| "center"
| "anchor" |
| "anchor" |
arrowPaddingarrow-padding | The amount of padding between the arrow and the popup’s edges. Type: number |
| 10 |
flip | If the popup doesn’t fit in the boundary with the placement anymore, the popup will flip to the opposite side to keep it in view. You can also use the flip-fallback-placements attribute to further configure how the fallback placement is determined.Type: boolean |
| false |
flipFallbackPlacementsflip-fallback-placements | If the preferred placement doesn’t fit in the boundary anymore, the popup will try to fit in the fallback placements you specify until one fits. It must be a string of any number of placements separated by a space (e.g., top right bottom). If no placement fits, the flip fallback strategy will be used instead.Type: string |
| "" |
flipFallbackStrategyflip-fallback-strategy | When neither the preferred placement nor the fallback placements fit, this value will be use to determine whether the popup should be positioned using the best available fit based on available space or as it was initially preferred. Type: "best-fit"
| "initial" |
| "best-fit" |
flipBoundary | The flip boundary describes one or more clipping elements where 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. Type: Element | Element[] | undefined |
| ‐ |
flipPaddingflip-padding | The amount of padding in pixels to exceed before the flip behaviour will occur. Type: number |
| 0 |
shift | Moves the popup along the axis to keep it in view when clipped. Type: boolean |
| false |
shiftBoundary | The shift boundary describes one or more clipping elements where 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. Type: Element | Element[] | undefined |
| ‐ |
shiftPaddingshift-padding | The amount of padding in pixels to exceed before the shift behaviour will occur. Type: number |
| 0 |
autoSizeauto-size | If set, the popup will automatically resize itself to prevent it from overflowing. Type: "horizontal"
| "vertical"
| "both" | undefined |
| ‐ |
sync | Syncs the popup’s width or height to that of the anchor element. Type: "width" | "height" | "both" | undefined |
| ‐ |
autoSizeBoundary | The auto‐size boundary describes one or more clipping elements where 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. Type: Element | Element[] | undefined |
| ‐ |
autoSizePaddingauto-size-padding | The amount of padding in pixels to exceed before the auto‐size behaviour will occur. Type: number |
| 0 |
hoverBridgehover-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 cursor technically never leaves the element. The hover bridge is only drawn if the popup is active.Type: boolean |
| false |
updateComplete | A read‐only promise that resolves when the component has finished updating. | ‐ |
Learn more about attributes and properties.
Slots#
| Name | Description |
|---|---|
| (default) | The popup’s content. |
anchor | The element the popup will be anchored to. If the anchor lives outside of the popup, you can use the anchor attribute/property instead. |
Learn more about using slots.
Methods#
| Name | Description | Arguments |
|---|---|---|
reposition() | Forces the popup to recalculate and reposition itself. | ‐ |
Learn more about methods.
Events#
| Name | Description | Event detail |
|---|---|---|
pc-reposition | Emitted when the popup is repositioned. This even can fire a lot, so avoid putting expensive operations in your event listener or consider debouncing it. | ‐ |
Learn more about events.
Custom properties#
| Name | Description | Default |
|---|---|---|
--arrow-size | The arrow’s size. The arrow won’t be shown unless the arrow attribute is used. | var(--pc-tooltip-arrow-size) |
--arrow-color | The arrow’s colour. | var(--pc-color-neutral-fill-normal) |
Learn more about customising custom properties.
Parts#
| Name | Description |
|---|---|
arrow | The arrow’s container. Avoid setting positioning properties, as these values are assigned dynamically as the popup moves. |
popup | The popup’s container. |
hover-bridge | The hover bridge element. This is only available if the hover-bridge attribute is set. |
Learn more about customising CSS parts.
Importing#
If you’re using the autoloader or the standard loader, you can skip this section. But if you’re cherry picking, you can use any of the following snippets to import this component.
To manually import this component from the CDN, copy this code snippet and paste it in your HTML.
<script type="module" src="https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.1/cdn/components/popup/popup.js"></script>To manually import this component from the CDN, copy this code snippet and paste it in your JavaScript file.
import "https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.1/cdn/components/popup/popup.js";To manually import this component from npm, copy this code snippet and paste it in your JavaScript file.
import "placer-toolkit/dist/components/popup/popup.js";