Popup
Examples
Basic Popup (click to toggle)
Placement
Distance and Skidding
Flip and Shift
Arrow
Auto Size
Sync Width/Height
Fixed Strategy
External Anchor
Importing
Slots
Properties
Events
Methods
Custom Properties
Parts

Popup

<terra-popup> | TerraPopup

Since 1.0

stable

Popup is a utility that lets you declaratively anchor “popup” containers to another element.

Popup

Popup is a utility component that lets you declaratively anchor “popup” containers to another element. It uses Floating UI under the hood to handle positioning, flipping, shifting, and more.

Examples

A simple popup anchored to a button. This example shows how to toggle the popup’s active state when the anchor is clicked.

<terra-popup id="basic-popup">
  <terra-button id="basic-popup-anchor" slot="anchor">Toggle popup</terra-button>
  <div style="padding: 1rem; background: white; border: 1px solid var(--terra-color-carbon-20); border-radius: var(--terra-border-radius-medium);">
    This is a popup!
  </div>
</terra-popup>

<script type="module">
  const popup = document.querySelector('#basic-popup');
  const anchor = document.querySelector('#basic-popup-anchor');

  anchor.addEventListener('click', () => {
    popup.active = !popup.active;
  });
</script>

Placement

The placement attribute controls where the popup appears relative to its anchor.

<div style="display: flex; gap: 1rem; flex-wrap: wrap; padding: 2rem;">
  <terra-popup id="popup-top" placement="top">
    <terra-button id="popup-top-anchor" slot="anchor">Top</terra-button>
    <div style="padding: 0.5rem; background: white; border: 1px solid var(--terra-color-carbon-20); border-radius: var(--terra-border-radius-medium);">Popup</div>
  </terra-popup>

  <terra-popup id="popup-bottom" placement="bottom">
    <terra-button id="popup-bottom-anchor" slot="anchor">Bottom</terra-button>
    <div style="padding: 0.5rem; background: white; border: 1px solid var(--terra-color-carbon-20); border-radius: var(--terra-border-radius-medium);">Popup</div>
  </terra-popup>

  <terra-popup id="popup-left" placement="left">
    <terra-button id="popup-left-anchor" slot="anchor">Left</terra-button>
    <div style="padding: 0.5rem; background: white; border: 1px solid var(--terra-color-carbon-20); border-radius: var(--terra-border-radius-medium);">Popup</div>
  </terra-popup>

  <terra-popup id="popup-right" placement="right">
    <terra-button id="popup-right-anchor" slot="anchor">Right</terra-button>
    <div style="padding: 0.5rem; background: white; border: 1px solid var(--terra-color-carbon-20); border-radius: var(--terra-border-radius-medium);">Popup</div>
  </terra-popup>
</div>

<script type="module">
  function wirePopup(idPrefix) {
    const popup = document.querySelector(`#popup-${idPrefix}`);
    const anchor = document.querySelector(`#popup-${idPrefix}-anchor`);
    if (popup && anchor) {
      anchor.addEventListener('click', () => {
        popup.active = !popup.active;
      });
    }
  }

  ['top', 'bottom', 'left', 'right'].forEach(wirePopup);
</script>

Distance and Skidding

Use the distance attribute to set the distance between the anchor and popup, and skidding to offset along the anchor.

<terra-popup id="distance-popup" distance="20" skidding="10">
  <terra-button id="distance-popup-anchor" slot="anchor">With Distance</terra-button>
  <div style="padding: 1rem; background: white; border: 1px solid var(--terra-color-carbon-20); border-radius: var(--terra-border-radius-medium);">
    This popup has distance and skidding applied.
  </div>
</terra-popup>

<script type="module">
  const distancePopup = document.querySelector('#distance-popup');
  const distanceAnchor = document.querySelector('#distance-popup-anchor');

  distanceAnchor?.addEventListener('click', () => {
    distancePopup.active = !distancePopup.active;
  });
</script>

Flip and Shift

Use the flip attribute to automatically flip the popup to the opposite side when it doesn’t fit, and shift to move it along the axis to keep it in view.

<div style="display: flex; gap: 1rem; padding: 2rem;">
  <terra-popup id="flip-popup" placement="top" flip>
    <terra-button id="flip-popup-anchor" slot="anchor">Flip Enabled</terra-button>
    <div style="padding: 1rem; background: white; border: 1px solid var(--terra-color-carbon-20); border-radius: var(--terra-border-radius-medium);">
      This will flip to bottom if there's no space above.
    </div>
  </terra-popup>

  <terra-popup id="shift-popup" placement="right" shift>
    <terra-button id="shift-popup-anchor" slot="anchor">Shift Enabled</terra-button>
    <div style="padding: 1rem; background: white; border: 1px solid var(--terra-color-carbon-20); border-radius: var(--terra-border-radius-medium);">
      This will shift to stay in view.
    </div>
  </terra-popup>
</div>

<script type="module">
  [['flip-popup', 'flip-popup-anchor'], ['shift-popup', 'shift-popup-anchor']].forEach(
    ([popupId, anchorId]) => {
      const popup = document.querySelector(`#${popupId}`);
      const anchor = document.querySelector(`#${anchorId}`);
      if (popup && anchor) {
        anchor.addEventListener('click', () => {
          popup.active = !popup.active;
        });
      }
    }
  );
</script>

Arrow

Add an arrow to the popup using the arrow attribute.

<terra-popup id="arrow-popup" arrow>
  <terra-button id="arrow-popup-anchor" slot="anchor">With Arrow</terra-button>
  <div style="padding: 1rem; background: white; border: 1px solid var(--terra-color-carbon-20); border-radius: var(--terra-border-radius-medium);">
    This popup has an arrow pointing to the anchor.
  </div>
</terra-popup>

<script type="module">
  const arrowPopup = document.querySelector('#arrow-popup');
  const arrowAnchor = document.querySelector('#arrow-popup-anchor');

  arrowAnchor?.addEventListener('click', () => {
    arrowPopup.active = !arrowPopup.active;
  });
</script>

Auto Size

Use the auto-size attribute to automatically resize the popup to prevent overflow.

<terra-popup id="auto-size-popup" auto-size="vertical" style="max-width: 200px;">
  <terra-button id="auto-size-popup-anchor" slot="anchor">Auto Size</terra-button>
  <div style="padding: 1rem; background: white; border: 1px solid var(--terra-color-carbon-20); border-radius: var(--terra-border-radius-medium);">
    This popup will automatically resize vertically to fit in the viewport.
  </div>
</terra-popup>

<script type="module">
  const autoSizePopup = document.querySelector('#auto-size-popup');
  const autoSizeAnchor = document.querySelector('#auto-size-popup-anchor');

  autoSizeAnchor?.addEventListener('click', () => {
    autoSizePopup.active = !autoSizePopup.active;
  });
</script>

Sync Width/Height

Use the sync attribute to match the popup’s width or height to the anchor element.

<terra-popup id="sync-popup" sync="width">
  <terra-button id="sync-popup-anchor" slot="anchor" style="width: 200px;">Sync Width</terra-button>
  <div style="padding: 1rem; background: white; border: 1px solid var(--terra-color-carbon-20); border-radius: var(--terra-border-radius-medium);">
    This popup's width matches the button.
  </div>
</terra-popup>

<script type="module">
  const syncPopup = document.querySelector('#sync-popup');
  const syncAnchor = document.querySelector('#sync-popup-anchor');

  syncAnchor?.addEventListener('click', () => {
    syncPopup.active = !syncPopup.active;
  });
</script>

Fixed Strategy

Use the strategy="fixed" attribute when the popup needs to escape overflow containers.

Scroll down to see the popup…

<div style="height: 200px; overflow: auto; border: 1px solid var(--terra-color-carbon-20); padding: 1rem;">
  <p>Scroll down to see the popup...</p>
  <div style="height: 300px;"></div>
  <terra-popup id="fixed-popup" strategy="fixed">
    <terra-button id="fixed-popup-anchor" slot="anchor">Fixed Strategy</terra-button>
    <div style="padding: 1rem; background: white; border: 1px solid var(--terra-color-carbon-20); border-radius: var(--terra-border-radius-medium);">
      This popup uses fixed positioning to escape the overflow container.
    </div>
  </terra-popup>
</div>

<script type="module">
  const fixedPopup = document.querySelector('#fixed-popup');
  const fixedAnchor = document.querySelector('#fixed-popup-anchor');

  fixedAnchor?.addEventListener('click', () => {
    fixedPopup.active = !fixedPopup.active;
  });
</script>

External Anchor

You can anchor the popup to an element outside of it using the anchor attribute.

External Anchor

<terra-button id="external-anchor">External Anchor</terra-button>
<terra-popup id="external-popup" anchor="#external-anchor">
  <div style="padding: 1rem; background: white; border: 1px solid var(--terra-color-carbon-20); border-radius: var(--terra-border-radius-medium);">
    This popup is anchored to the button above.
  </div>
</terra-popup>

<script type="module">
  const externalPopup = document.querySelector('#external-popup');
  const externalAnchor = document.querySelector('#external-anchor');

  externalAnchor?.addEventListener('click', () => {
    externalPopup.active = !externalPopup.active;
  });
</script>

[component-metadata:terra-popup]

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.

Script

Import

Bundler

React

To import this component from the CDN using a script tag:

<script type="module" src="https://cdn.jsdelivr.net/npm/@nasa-terra/components@0.0.138/cdn/components/popup/popup.js"></script>

To import this component from the CDN using a JavaScript import:

import 'https://cdn.jsdelivr.net/npm/@nasa-terra/components@0.0.138/cdn/components/popup/popup.js';

To import this component using a bundler:

import '@nasa-terra/components/dist/components/popup/popup.js';

To import this component as a React component:

import TerraPopup from '@nasa-terra/components/dist/react/popup';

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 or property instead.

Learn more about using slots.

Properties

Name	Description	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'`	`'absolute'`
`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
`terra-reposition`	`onTerraReposition`	Emitted when the popup is repositioned. This event can fire a lot, so avoid putting expensive operations in your listener or consider debouncing it.	-

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
`--arrow-size`	The size of the arrow. Note that an arrow won’t be shown unless the `arrow` attribute is used.	6px
`--arrow-color`	The color of the arrow.	var(–terra-color-carbon-black)
`--auto-size-available-width`	A read-only custom property that determines the amount of width the popup can be before overflowing. Useful for positioning child elements that need to overflow. This property is only available when using `auto-size`.
`--auto-size-available-height`	A read-only custom property that determines the amount of height the popup can be before overflowing. Useful for positioning child elements that need to overflow. This property is only available when using `auto-size`.

Learn more about customizing CSS custom properties.

Parts

Name	Description
`arrow`	The arrow’s container. Avoid setting `top\|bottom\|left\|right` properties, as these values are assigned dynamically as the popup moves. This is most useful for applying a background color to match the popup, and maybe a border or box shadow.
`popup`	The popup’s container. Useful for setting a background color, box shadow, etc.
`hover-bridge`	The hover bridge element. Only available when the `hover-bridge` option is enabled.

Learn more about customizing CSS parts.

Popup

Examples

Basic Popup (click to toggle)

Placement

Distance and Skidding

Flip and Shift

Arrow

Auto Size

Sync Width/Height

Fixed Strategy

External Anchor

Importing

Slots

Properties

Events

Methods

Custom Properties

Parts