skip to content

With the Angular CDK's flexible connected position strategy, how is a fallback chosen when the preferred position does not fit, and what do push and flexible dimensions change?

level: seniorimportance: should knowfreq 30%

answer

  1. list order matters first
  2. fits completely, then flexibly, then pushed
  3. flexible fits need minimum sizes
  4. the directive turns push off
  5. weight and panelClass per position

basics

~20 s

The strategy applies the first listed position that fits the viewport completely; otherwise a position that fits after shrinking to minWidth or minHeight; otherwise it pushes the least off-screen one into view; otherwise it uses that one as is.

solid answer

~40 s

`FlexibleConnectedPositionStrategy.apply()` walks the positions from `withPositions` in order and applies the first one whose overlay fits entirely inside the viewport, narrowed by `withViewportMargin`. If none does and flexible dimensions are on, it collects positions where the overlay would fit once shrunk to the config's `minWidth`/`minHeight`, and picks the one with the largest available box times its `weight`. If there are none, and push is on, it takes the position with the most visible area and pushes it on-screen; with push off, it applies that position partly off-screen. The strategy itself defaults to push and flexible dimensions on, but `cdkConnectedOverlay` passes both as false unless you set `cdkConnectedOverlayPush` and `cdkConnectedOverlayFlexibleDimensions`. Flexible dimensions do nothing without minimum sizes.

go deeper

for a junior

Recall that positions are tried in the order listed and that a later entry is a fallback for when the first does not fit.

for a middle

Explain the four steps, complete fit, flexible fit, push, least bad, and what originX, originY, overlayX and overlayY mean.

for a senior

Diagnose the edge cases: flexible sizing doing nothing without minimums, directive panels overflowing because push is off, flipping during scroll fixed by locking, and stale positions after content grows.

for a principal

Agree placement rules for every anchored surface in the product, preference order, push or not, and margins, and ship them as shared position lists rather than per-feature guesses.

## What the strategy positions against The Angular CDK's `FlexibleConnectedPositionStrategy` anchors an overlay to an **origin**, an element or a point, by connecting one point on the origin to one point on the overlay. Each candidate is a `ConnectedPosition`: - `originX` (`'start' | 'center' | 'end'`) and `originY` (`'top' | 'center' | 'bottom'`) pick the point on the origin; - `overlayX` and `overlayY` pick the point on the overlay that meets it; - optional `offsetX`, `offsetY`, `weight` and `panelClass` tune each candidate. `start` and `end` follow the text direction, so the same list works in right-to-left layouts. Fit is judged against the **viewport**, shrunk by `withViewportMargin` (a number, or per-side values since 21), not against the grid's scroll container. ## The selection algorithm Every time `apply()` runs, on attach, on `updatePosition()`, on reposition scrolling or on window resize, the strategy follows this order: 1. **Complete fit.** Walk the positions in the order given. The first whose overlay fits entirely inside the narrowed viewport is applied immediately. Order is preference; later entries are fallbacks. 2. **Flexible fit.** If flexible dimensions are on, a position also qualifies when each overflowing axis has room for the overlay's `minHeight` or `minWidth` from `OverlayConfig`. Among those, the one with the largest available box multiplied by its `weight` (default 1) wins, and the overlay is constrained to that box. 3. **Push.** If nothing fits even flexibly and push is on, take the position with the most visible area and push the overlay on-screen. 4. **Least bad.** With push off, apply that same position and let it overflow. Two consequences follow from the source. Without `minWidth`/`minHeight`, step 2 can never succeed for an overflowing axis, so flexible dimensions quietly do nothing. And `weight` only matters among flexible fits; it never overrides list order for complete fits. ## Defaults: strategy versus directive | Setting | Method | Strategy default | `cdkConnectedOverlay` default | |---|---|---|---| | Push on-screen | `withPush()` | on | off (`cdkConnectedOverlayPush`) | | Flexible dimensions | `withFlexibleDimensions()` | on | off (`cdkConnectedOverlayFlexibleDimensions`) | | Grow after open | `withGrowAfterOpen()` | off | off | | Lock position | `withLockedPosition()` | off | off (`cdkConnectedOverlayLockPosition`) | | Viewport margin | `withViewportMargin()` | 0 | 0 | The same panel can therefore slide back into view when built from code and overflow the edge when declared with the directive. ## Applying it to a spreadsheet grid A cell editor should cover its cell, and near the bottom of the screen it should grow upward from the cell's bottom edge instead: ```ts const position = createFlexibleConnectedPositionStrategy(injector, cell) .withPositions([ {originX: 'start', originY: 'top', overlayX: 'start', overlayY: 'top'}, {originX: 'start', originY: 'bottom', overlayX: 'start', overlayY: 'bottom', panelClass: 'editor-grows-up'}, {originX: 'end', originY: 'top', overlayX: 'end', overlayY: 'top'}, ]) .withViewportMargin(8) .withPush(false) .withLockedPosition(); ``` - The `panelClass` on the second entry is added to the pane only while that position is active, so CSS can flip a caret or a shadow. - `withPush(false)` keeps the editor aligned with its cell; a pushed editor that no longer covers the cell is confusing. - `withLockedPosition()` reuses the last applied position on later `apply()` calls such as reposition scrolling, so the editor does not jump between above and below while the user scrolls. A window resize still recalculates from scratch. A column-filter panel taller than the space below its header is the case for flexible dimensions: set `minHeight` in the config, keep flexible dimensions on, and give the panel's list `overflow: auto` so it scrolls inside the shrunken box. ## Debugging a panel in the wrong place 1. Log `positionChanges` to see which `connectionPair` was applied; if it is the last entry, nothing earlier fit. 2. Check whether push or flexible dimensions are actually on: the directive turns both off. 3. Check `minWidth`/`minHeight` if you expected the panel to shrink. 4. Check the viewport margin: a large margin can make every position "not fit" on small screens. 5. If the panel is right on open but wrong after its content changes, add an `updatePosition()` call. ## Observing and re-running - `positionChanges` emits a `ConnectedOverlayPositionChange` with the applied `connectionPair` and, if you passed `withScrollableContainers`, scroll-visibility flags. - The position is computed after the content renders. If the editor grows later, for example when a validation message appears, call `overlayRef.updatePosition()`. - Listing no positions throws `At least one position is required`.

  • Flexible dimensions are on, yet the too-tall filter panel still overflows the bottom of the screen. What is missing?
    A minimum size. A position counts as a flexible fit only if the axis that overflows has room for the config's `minHeight` (or `minWidth`). With no minimum, the strategy skips the flexible step and falls through to pushing or overflowing. Set `minHeight` on the overlay and let the panel's inner list scroll.
  • What does withLockedPosition change, and when is the position recalculated anyway?
    After the first placement, later `apply()` calls reuse the last applied position instead of re-running the search, so the overlay does not flip while the user scrolls. A viewport resize resets the strategy to behave like an initial render, so it searches again.

  • The strategy picks whichever position leaves the most free space.
  • Weight decides between positions that all fit completely.
  • Flexible dimensions shrink the panel even without minWidth or minHeight.
  • cdkConnectedOverlay pushes panels on-screen by default, like the strategy.
  • Fit is measured against the scroll container that holds the origin.

Assumes Angular CDK 22; the createFlexibleConnectedPositionStrategy function arrived in 20, and per-side withViewportMargin values arrived in 21.