CSS @position-try At-Rule

CSS @position-try At-Rule

The @position-try at-rule defines a named fallback position for an anchor-positioned element. When an element such as a tooltip or popover would overflow its containing block or the viewport, the browser can try alternative positions to keep it visible. Custom fallback positions can change placement, margins, sizing, and alignment.

@position-try Syntax

@position-try --fallback-name {
  position-area: bottom;
}

The @position-try at-rule begins with a custom name starting with two hyphens, followed by a block containing positioning descriptors.

The name is referenced by the position-try-fallbacks property or the position-try shorthand on an anchor-positioned element.

@position-try --below-anchor {
  position-area: bottom;
}
.tooltip {
  position-try-fallbacks: --below-anchor;
}

The --below-anchor name identifies a custom fallback that places the tooltip below its anchor.

Defining a fallback does not apply it automatically. The positioned element must reference the fallback name.

How @position-try Works

Anchor positioning allows an absolutely or fixed-positioned element to be placed relative to another element, called its anchor.

A tooltip may normally appear above a button. If the button is close to the top of the viewport, there may not be enough space for the tooltip.

The @position-try at-rule defines an alternative layout that the browser can use when the preferred position overflows.

@position-try --move-below {
  position-area: bottom;
}
.tooltip {
  position: absolute;
  position-anchor: --button-anchor;
  position-area: top;
  position-try-fallbacks: --move-below;
}

The browser first attempts to place the tooltip above its anchor. If that position would overflow, it tries the custom position below the anchor.

If no fallback resolves the overflow, the browser can return to the original position.

The fallback mechanism is based on available space. It does not automatically prevent the positioned element from overlapping unrelated content.

Anchor Positioning

The @position-try at-rule works with CSS anchor positioning. An anchor must be established before a positioned element can use it.

Defining an Anchor

.button {
  anchor-name: --button-anchor;
}

The anchor-name property assigns a custom name to the anchor element.

Positioning Relative to the Anchor

.tooltip {
  position: absolute;
  position-anchor: --button-anchor;
  position-area: top;
}

The position-anchor property associates the tooltip with the named anchor. The position-area property places it above the anchor.

Adding a Fallback

@position-try --below {
  position-area: bottom;
}
.tooltip {
  position: absolute;
  position-anchor: --button-anchor;
  position-area: top;
  position-try-fallbacks: --below;
}

The browser can move the tooltip below the anchor when the preferred top position does not fit.

Without an anchor relationship, the custom fallback cannot provide the intended anchor-relative positioning.

Supported Descriptors

The @position-try block accepts specific groups of CSS positioning-related declarations.

Changing Position and Size

@position-try --compact-right {
  position-area: right;
  width: 140px;
  margin-left: 10px;
}

This fallback places the element to the right of its anchor, changes its width, and adds spacing between the two elements.

Properties unrelated to positioning, such as background-color, color, and font-size, are not valid descriptors inside @position-try.

The !important flag is not permitted on declarations inside a @position-try block.

Custom Fallback Positions

Custom fallback positions are useful when a positioned element needs more than a simple change of direction.

Moving an Element to the Left

@position-try --left-side {
  position-area: left;
  margin-right: 12px;
  width: 150px;
}

This fallback places the element to the left of its anchor with a 12-pixel gap.

Using the anchor() Function

@position-try --below-with-offset {
  position-area: none;
  top: calc(anchor(bottom) + 10px);
  justify-self: anchor-center;
}

The anchor() function references the bottom edge of the anchor. The calc() function adds 10 pixels of spacing.

The justify-self: anchor-center declaration centers the positioned element along the anchor's inline axis.

The position-area: none declaration clears any existing position-area placement that could conflict with the explicit inset positioning.

Changing the Anchor

@position-try --alternate-anchor {
  position-anchor: --secondary-anchor;
  position-area: bottom;
}

A custom fallback can reference another named anchor. The alternate anchor must exist and be valid for the positioned element.

Multiple Fallback Positions

Multiple @position-try rules can define different fallback layouts.

@position-try --below {
  position-area: bottom;
  margin-top: 10px;
}
@position-try --right {
  position-area: right;
  margin-left: 10px;
}
@position-try --left {
  position-area: left;
  margin-right: 10px;
}
.tooltip {
  position: absolute;
  position-anchor: --button-anchor;
  position-area: top;
  position-try-fallbacks: --below, --right, --left;
}

The browser first attempts the original position above the anchor. If that position overflows, it tries the named fallback positions in the specified order.

The first fallback that fits within the relevant overflow boundaries is selected.

If none of the fallbacks fits, the browser generally returns to the original position.

Custom fallback names can be reused across multiple anchor-positioned elements.

Predefined Fallback Positions

CSS provides predefined fallback options that can be used without creating a custom @position-try rule.

.tooltip {
  position: absolute;
  position-anchor: --button-anchor;
  position-area: top;
  position-try-fallbacks: flip-block, flip-inline;
}

This example uses built-in fallback tactics instead of named custom positions.

Combining Custom and Predefined Fallbacks

@position-try --compact-right {
  position-area: right;
  width: 140px;
}
.tooltip {
  position-try-fallbacks: flip-block, --compact-right;
}

The browser can first try flipping the element and then try the custom right-side position.

Use a custom @position-try rule when the fallback needs additional adjustments to margins, dimensions, or alignment.

Fallback Priority

The position-try-order property controls how fallback positions are prioritized.

.tooltip {
  position: absolute;
  position-anchor: --button-anchor;
  position-area: top;
  position-try-order: most-height;
  position-try-fallbacks: bottom, right, left;
}

This example requests that the browser prioritize placement according to available height rather than simply following the declared fallback order.

Using the position-try Shorthand

.tooltip {
  position-try: most-height bottom, right, left;
}

The position-try shorthand combines position-try-order and position-try-fallbacks into one declaration.

@position-try Example

The following example creates a tooltip anchored to a button. The tooltip normally appears above the button but moves below it when there is insufficient space.

HTML

<div class="demo">
  <button class="anchor-button" type="button">Anchor Button</button>
  <div class="tooltip" role="note">
    This tooltip changes position when needed.
  </div>
</div>

CSS

@position-try --below-anchor {
  position-area: bottom;
  margin-top: 10px;
  margin-bottom: 0;
}
.demo {
  position: relative;
  height: 180px;
  padding: 15px;
  border: 1px solid #ddd;
}
.anchor-button {
  anchor-name: --demo-anchor;
  padding: 10px 16px;
}
.tooltip {
  position: absolute;
  position-anchor: --demo-anchor;
  position-area: top;
  position-try-fallbacks: --below-anchor;
  width: 180px;
  padding: 10px;
  margin-bottom: 10px;
  background-color: #0056b3;
  color: #fff;
  border-radius: 4px;
}

The anchor-name property identifies the button as the anchor. The tooltip uses position-area: top as its preferred placement and the named fallback to move below the button when necessary.

The fallback adjusts both placement and spacing. In a supported browser, the actual position depends on the available space around the anchor.

Browser Support

The @position-try at-rule is Baseline Newly available since January 2026. It works in current major browser versions, but may not be available in older browsers. See Can I Use? for compatibility information.

Specifications

The @position-try at-rule is defined in CSS Anchor Positioning Module Level 1. The specification describes custom position options, the supported positioning descriptors, and how fallback options are selected when an anchored element would overflow.

CSS Anchor Positioning Module Level 1