Semantic-Org/Semantic-UI · warning

Popup does not fit within the boundaries of the viewport

Error message

Popup does not fit within the boundaries of the viewport

What it means

After tentatively placing the popup, the module checks viewport boundaries (popup.js:901-928). It tries alternative positions up to settings.maxSearchDepth; if every position is 'offstage' and settings.lastResort is falsy, it logs error.cannotPlace, removes the loading state, calls onUnplaceable, and returns false (popup.js:918-925). The popup is not shown.

Source

Thrown at src/definitions/modules/popup.js:1455

  // transition settings
  duration       : 200,
  transition     : 'scale',

  // distance away from activating element in px
  distanceAway   : 0,

  // number of pixels an element is allowed to be "offstage" for a position to be chosen (allows for rounding)
  jitter         : 2,

  // offset on aligning axis from calculated position
  offset         : 0,

  // maximum times to look for a position before failing (9 positions total)
  maxSearchDepth : 15,

  error: {
    invalidPosition : 'The position you specified is not a valid position',
    cannotPlace     : 'Popup does not fit within the boundaries of the viewport',
    method          : 'The method you called is not defined.',
    noTransition    : 'This module requires ui transitions <https://github.com/Semantic-Org/UI-Transition>',
    notFound        : 'The target or popup you specified does not exist on the page'
  },

  metadata: {
    activator : 'activator',
    content   : 'content',
    html      : 'html',
    offset    : 'offset',
    position  : 'position',
    title     : 'title',
    variation : 'variation'
  },

  className   : {
    active       : 'active',
    basic        : 'basic',

View on GitHub (pinned to 597843ab84)

Solutions

1. Set settings.lastResort to a valid position so the popup is shown there even if it overflows.
2. Reduce popup content size or set preferAdjacent:true / adjust distanceAway/offset so a position fits.
3. Increase settings.maxSearchDepth only if you have custom positions; otherwise enlarge the viewport/scroll container.

Example fix

// before
$('.btn').popup({ position: 'top center', content: veryLongHtml }); // no fit -> [91]

// after
$('.btn').popup({
  position: 'top center',
  lastResort: 'bottom center',
  content: veryLongHtml
});

// Provide a lastResort so a fit-less popup still shows
$('.btn').popup({ position: 'top center', lastResort: 'bottom center', content: html });

When it happens

Trigger: The viewport/scroll container is too small for the popup at every one of the nine positions given the target's location and the popup's size; settings.lastResort is not set; maxSearchDepth is exhausted. Common with large popups, zoomed/very small windows, or targets near screen corners with big popups.

Common situations: Long tooltip/HTML popups on mobile; target pinned to a viewport edge; popup inside a tiny scroll container; margin/padding inflating popup size; responsive layouts where the available space collapses.

Related errors

• The position you specified is not a valid position
• This module requires ui transitions <https://github.com/Sema
• The target or popup you specified does not exist on the page
• There were no elements that matched the specified selector
• Cannot search. No source used, and Semantic API module was n

AI-assisted analysis of Semantic-Org/Semantic-UI@597843ab84 (2026-08-13). Data as JSON: /api/errors/436a2e1fc0b4efbc. Report an issue: GitHub.