Archive

Archive for October, 2024

CSS Anchor Positioning Guide

October 2nd, 2024 No comments
Square labeled as "anchor"

Not long ago, if we wanted a tooltip or popover positioned on top of another element, we would have to set our tooltip’s position to something other than static and use its inset/transform properties to place it exactly where we want. This works, but the element’s position is susceptible to user scrolls, zooming, or animations since the tooltip could overflow off of the screen or wind up in an awkward position. The only way to solve this was using JavaScript to check whenever the tooltip goes out of bounds so we can correct it… again in JavaScript.

CSS Anchor Positioning gives us a simple interface to attach elements next to others just by saying which sides to connect — directly in CSS. It also lets us set a fallback position so that we can avoid the overflow issues we just described. For example, we might set a tooltip element above its anchor but allow it to fold underneath the anchor when it runs out of room to show it above.

Anchor positioning is different from a lot of other features as far as how quickly it’s gained browser support: its first draft was published on June 2023 and, just a year later, it was released on Chrome 125. To put it into perspective, the first draft specification for CSS variables was published in 2012, but it took four years for them to gain wide browser support.

So, let’s dig in and learn about things like attaching target elements to anchor elements and positioning and sizing them.

Quick reference

/* Define an anchor element */
.anchor {
  anchor-name: --my-anchor;
}
/* Anchor a target element */
.target {
  position: absolute;
  position-anchor: --my-anchor;
}
/* Position a target element */
.target { 
  position-area: start end;
}
Table of contents
  1. Basics and terminology
  2. Attaching targets to anchors
  3. Positioning targets
  4. Setting fallback positions
  5. Custom position and size fallbacks
  6. Multiple anchors
  7. Accessibility
  8. Browser support
  9. Spec changes
  10. Known bugs
  11. Almanac references
  12. Further reading

Basics and terminology

At its most basic, CSS Anchor Positioning introduces a completely new way of placing elements on the page relative to one another. To make our lives easier, we’re going to use specific names to clarify which element is connecting to which:

  • Anchor: This is the element used as a reference for positioning other elements, hence the anchor name.
  • Target: This is an absolutely positioned element placed relative to one or more anchors. The target is the name we will use from now on, but you will often find it as just an “absolutely positioned element” in the spec.

For the following code examples and demos, you can think of these as just two

elements next to one another.

<div class="anchor">anchor</div>
<div class="target">target</div>

CSS Anchor Positioning is all about elements with absolute positioning (i.e., display: absolute), so there are also some concepts we have to review before diving in.

  • Containing Block: This is the box that contains the elements. For an absolute element, the containing block is the viewport the closest ancestor with a position other than static or certain values in properties like contain or filter.
  • Inset-Modified Containing Block (IMCB): For an absolute element, inset properties (top, right, bottom, left, etc.) reduce the size of the containing block into which it is sized and positioned, resulting in a new box called the inset-modified containing block, or IMCB for short. This is a vital concept to know since properties we’re covering in this guide — like position-area and position-try-order — rely on this concept.

Attaching targets to anchors

We’ll first look at the two properties that establish anchor positioning. The first, anchor-name, establishes the anchor element, while the second, position-anchor, attaches a target element to the anchor element.

anchor-name

A normal element isn’t an anchor by default — we have to explicitly make an element an anchor. The most common way is by giving it a name, which we can do with the anchor-name property.

anchor-name: none | <dashed-ident>#

The name must be a , that is, a custom name prefixed with two dashes (--), like --my-anchor or --MyAnchor.

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

This gives us an anchor element. All it needs is something anchored to it. That’s what we call the “target” element which is set with the position-anchor property.

Square labeled as "target"

position-anchor

The target element is an element with an absolute position linked to an anchor element matching what’s declared on the anchor-name property. This attaches the target element to the anchor element.

position-anchor: auto | <anchor-element>

It takes a valid . So, if we establish another element as the “anchor” we can set the target with the position-anchor property:

.target {
  position: absolute;
  position-anchor: --my-anchor;
}

Normally, if a valid anchor element isn’t found, then other anchor properties and functions will be ignored.

Positioning targets

Now that we know how to establish an anchor-target relationship, we can work on positioning the target element in relation to the anchor element. The following two properties are used to set which side of the anchor element the target is positioned on (position-area) and conditions for hiding the target element when it runs out of room (position-visibility).

Anchor element with target elements spanning around it.

position-area

The next step is positioning our target relative to its anchor. The easiest way is to use the position-area property, which creates an imaginary 3×3 grid around the anchor element and lets us place the target in one or more regions of the grid.

position-area: auto | <position-area>

It works by setting the row and column of the grid using logical values like start and end (dependent on the writing mode); physical values like top, left, right, bottom and the center shared value, then it will shrink the target’s IMCB into the region of the grid we chose.

.target {
  position-area: top right;
  /* or */
  position-area: start end;
}

Logical values refer to the containing block’s writing mode, but if we want to position our target relative to its writing mode we would prefix it with the self value.

.target {
  position-area: self-start self-end;
}

There is also the center value that can be used in every axis.

.target {
  position-area: center right;
  /* or */
  position-area: start center;
}

To place a target across two adjacent grid regions, we can use the prefix span- on any value (that isn’t center) a row or column at a time.

.target {
  position-area: span-top left;
  /* or */
  position-area: span-start start;
}

Finally, we can span a target across three adjacent grid regions using the span-all value.

.target {
  position-area: bottom span-all;
  /* or */
  position-area: end span-all;
}

You may have noticed that the position-area property doesn’t have a strict order for physical values; writing position-area: top left is the same as position-area: left top, but the order is important for logical value since position-area: start end is completely opposite to position-area: end start.

We can make logical values interchangeable by prefixing them with the desired axis using y-, x-, inline- or block-.

.target {
  position-area: inline-end block-start;
  /* or */
  position-area: y-start x-end;
}
CodePen Embed Fallback
CodePen Embed Fallback
Examples on each position-visibility value: always showing the target, anchors-visible hiding it when the anchor goes out of screen and no-overflow hiding it when the target overflows

position-visibility

It provides certain conditions to hide the target from the viewport.

position-visibility: always | anchors-visible | no-overflow
  • always: The target is always displayed without regard for its anchors or its overflowing status.
  • no-overflow: If even after applying the position fallbacks, the target element is still overflowing its containing block, then it is strongly hidden.
  • anchors-visible: If the anchor (not the target) has completely overflowed its containing block or is completely covered by other elements, then the target is strongly hidden.
position-visibility: always | anchors-visible | no-overflow
CodePen Embed Fallback

Setting fallback positions

Once the target element is positioned against its anchor, we can give the target additional instructions that tell it what to do if it runs out of space. We’ve already looked at the position-visibility property as one way of doing that — we simply tell the element to hide. The following two properties, however, give us more control to re-position the target by trying other sides of the anchor (position-try-fallbacks) and the order in which it attempts to re-position itself (position-try-order).

The two properties can be declared together with the position-try shorthand property — we’ll touch on that after we look at the two constituent properties.

Examples on each try-tactic: flip-block flipping the target from the top to the bottom, flip-inline from left to right and flip-start from left to top (single value) and top right to left bottom (two values)

position-try-fallbacks

This property accepts a list of comma-separated position fallbacks that are tried whenever the target overflows out of space in its containing block. The property attempts to reposition itself using each fallback value until it finds a fit or runs out of options.

position-try-fallbacks: none | [ [<dashed-ident> || <try-tactic>] | <'inset-area'>  ]#
  • none: Leaves the target’s position options list empty.
  • : Adds to the options list a custom @position-try fallback with the given name. If there isn’t a matching @position-try, the value is ignored.
  • : Creates an option list by flipping the target’s current position on one of three axes, each defined by a distinct keyword. They can also be combined to add up their effects.

    • The flip-block keyword swaps the values in the block axis.
    • The flip-inline keyword swaps the values in the inline axis.
    • The flip-start keyword swaps the values diagonally.
  • || : Combines a custom @try-option and a to create a single-position fallback. The keywords can also be combined to sum up their effects.
  • Uses the position-area syntax to move the anchor to a new position.
.target {
  position-try-fallbacks:
    --my-custom-position,
    --my-custom-position flip-inline,
    bottom left;
}
two targets sorrounding an anchor, positioned where the IMCB is the largest.

position-try-order

This property chooses a new position from the fallback values defined in the position-try-fallbacks property based on which position gives the target the most space. The rest of the options are reordered with the largest available space coming first.

position-try-order: normal | most-width | most-height | most-block-size | most-inline-size

What exactly does “more space” mean? For each position fallback, it finds the IMCB size for the target. Then it chooses the value that gives the IMCB the widest or tallest size, depending on which option is selected:

  • most-width
  • most-height
  • most-block-size
  • most-inline-size
.target {
  position-try-fallbacks: --custom-position, flip-start;
  position-try-order: most-width;
}

position-try

This is a shorthand property that combines the position-try-fallbacks and position-try-order properties into a single declaration. It accepts first the order and then the list of possible position fallbacks.

position-try: < "position-try-order" >? < "position-try-fallbacks" >;

So, we can combine both properties into a single style rule:

.target {
  position-try: most-width --my-custom-position, flip-inline, bottom left;
}

Custom position and size fallbacks

@position-try

This at-rule defines a custom position fallback for the position-try-fallbacks property.

@position-try <dashed-ident> {
  <declaration-list>
}

It takes various properties for changing a target element’s position and size and grouping them as a new position fallback for the element to try.

Imagine a scenario where you’ve established an anchor-target relationship. You want to position the target element against the anchor’s top-right edge, which is easy enough using the position-area property we saw earlier:

.target {
  position: absolute;
  position-area: top right;
  width: 100px;
}

See how the .target is sized at 100px? Maybe it runs out of room on some screens and is no longer able to be displayed at anchor’s the top-right edge. We can supply the .target with the fallbacks we looked at earlier so that it attempts to re-position itself on an edge with more space:

.target {
  position: absolute;
  position-area: top right;
  position-try-fallbacks: top left;
  position-try-order: most-width;
  width: 100px;
}

And since we’re being good CSSer’s who strive for clean code, we may as well combine those two properties with the position-try shorthand property:

.target {
  position: absolute;
  position-area: top right;
  position-try: most-width, flip-inline, bottom left;
  width: 100px;
}

So far, so good. We have an anchored target element that starts at the top-right corner of the anchor at 100px. If it runs out of space there, it will look at the position-try property and decide whether to reposition the target to the anchor’s top-left corner (declared as flip-inline) or the anchor’s bottom-left corner — whichever offers the most width.

But what if we want to simulataneously re-size the target element when it is re-positioned? Maybe the target is simply too dang big to display at 100px at either fallback position and we need it to be 50px instead. We can use the @position-try to do exactly that:

@position-try --my-custom-position {
  position-area: top left;
  width: 50px;
}

With that done, we now have a custom property called --my-custom-position that we can use on the position-try shorthand property. In this case, @position-try can replace the flip-inline value since it is the equivalent of top left:

@position-try --my-custom-position {
  position-area: top left;
  width: 50px;
}

.target {
  position: absolute;
  position-area: top right;
  position-try: most-width, --my-custom-position, bottom left;
  width: 100px;
}

This way, the .target element’s width is re-sized from 100px to 50px when it attempts to re-position itself to the anchor’s top-right edge. That’s a nice bit of flexibility that gives us a better chance to make things fit together in any layout.

Anchor functions

anchor()

You might think of the CSS anchor() function as a shortcut for attaching a target element to an anchor element — specify the anchor, the side we want to attach to, and how large we want the target to be in one fell swoop. But, as we’ll see, the function also opens up the possibility of attaching one target element to multiple anchor elements.

This is the function’s formal syntax, which takes up to three arguments:

anchor( <anchor-element>? && <anchor-side>, <length-percentage>? )

So, we’re identifying an anchor element, saying which side we want the target to be positioned on, and how big we want it to be. It’s worth noting that anchor() can only be declared on inset-related properties (e.g. top, left, inset-block-end, etc.)

.target {
  top: anchor(--my-anchor bottom);
  left: anchor(--my-anchor end, 50%);
}

Let’s break down the function’s arguments.

This argument specifies which anchor element we want to attach the target to. We can supply it with either the anchor’s name (see “Attaching targets to anchors”).

We also have the choice of not supplying an anchor at all. In that case, the target element uses an implicit anchor element defined in position-anchor. If there isn’t an implicit anchor, the function resolves to its fallback. Otherwise, it is invalid and ignored.

This argument sets which side of the anchor we want to position the target element to, e.g. the anchor’s top, left, bottom, right, etc.

But we have more options than that, including logical side keywords (inside, outside), logical direction arguments relative to the user’s writing mode (start, end, self-start, self-end) and, of course, center.

  • : Resolves to the of the corresponding side of the anchor element. It has physical arguments (top, left, bottom right), logical side arguments (inside, outside), logical direction arguments relative to the user’s writing mode (start, end, self-start, self-end) and the center argument.
  • : Refers to the position between the start (0%) and end (100%). Values below 0% and above 100% are allowed.

This argument is totally optional, so you can leave it out if you’d like. Otherwise, use it as a way of re-sizing the target elemenrt whenever it doesn’t have a valid anchor or position. It positions the target to a fixed or relative to its containing block.

Let’s look at examples using different types of arguments because they all do something a little different.

Using physical arguments
targets sorrounding the anchor. each with a different position

Physical arguments (top, right, bottom, left) can be used to position the target regardless of the user’s writing mode. For example, we can position the right and bottom inset properties of the target at the anchor(top) and anchor(left) sides of the anchor, effectively positioning the target at the anchor’s top-left corner:

.target {
  bottom: anchor(top);
  right: anchor(left);
}

Using logical side keywords
targets sorrounding the anchor. each with a different position

Logical side arguments (i.e., inside, outside), are dependent on the inset property they are in. The inside argument will choose the same side as its inset property, while the outside argument will choose the opposite. For example:

.target {
  left: anchor(outside);
  /* is the same as */
  left: anchor(right);

  top: anchor(inside);
  /* is the same as */
  top: anchor(top);
}

Using logical directions

targets sorrounding the anchor. each with a different position

Logical direction arguments are dependent on two factors:

  1. The user’s writing mode: they can follow the writing mode of the containing block (start, end) or the target’s own writing mode (self-start, self-end).
  2. The inset property they are used in: they will choose the same axis of their inset property.

So for example, using physical inset properties in a left-to-right horizontal writing would look like this:

.target {
  left: anchor(start);
  /* is the same as */
  left: anchor(left);

  top: anchor(end);
  /* is the same as */
  top: anchor(bottom);
}

In a right-to-left writing mode, we’d do this:

.target {
  left: anchor(start);
  /* is the same as */
  left: anchor(right);

  top: anchor(end);
  /* is the same as */
  top: anchor(bottom);
}

That can quickly get confusing, so we should also use logical arguments with logical inset properties so the writing mode is respected in the first place:

.target {
  inset-inline-start: anchor(end);
  inset-block-start: anchor(end);
}

Using percentage values
targets sorrounding the anchor. each with a different position

Percentages can be used to position the target from any point between the start (0%) and end (100% ) sides. Since percentages are relative to the user writing mode, is preferable to use them with logical inset properties.

.target {
  inset-inline-start: anchor(100%);
  /* is the same as */
  inset-inline-start: anchor(end);

  inset-block-end: anchor(0%);
  /* is the same as */
  inset-block-end: anchor(start);
}

Values smaller than 0% and bigger than 100% are accepted, so -100% will move the target towards the start and 200% towards the end.

.target {
  inset-inline-start: anchor(200%);
  inset-block-end: anchor(-100%);
}

Using the center keyword
targets sorrounding the anchor. each with a different position

The center argument is equivalent to 50%. You could say that it’s “immune” to direction, so there is no problem if we use it with physical or logical inset properties.

.target {
  position: absolute;
  position-anchor: --my-anchor;

  left: anchor(center);
  bottom: anchor(top);
}

anchor-size()

The anchor-size() function is unique in that it sizes the target element relative to the size of the anchor element. This can be super useful for ensuring a target scales in size with its anchor, particularly in responsive designs where elements tend to get shifted, re-sized, or obscured from overflowing a container.

The function takes an anchor’s side and resolves to its , essentially returning the anchor’s width, height, inline-size or block-size.

anchor-size( [ <anchor-element> || <anchor-size> ]? , <length-percentage>? )
anchor with an anchor-size() function on each side

Here are the arguments that can be used in the anchor-size() function:

  • : Refers to the side of the anchor element.
  • : This optional argument can be used as a fallback whenever the target doesn’t have a valid anchor or size. It returns a fixed or relative to its containing block.

And we can declare the function on the target element’s width and height properties to size it with the anchor — or both at the same time!

.target {
  width: anchor-size(width, 20%); /* uses default anchor */`
  height: anchor-size(--other-anchor inline-size, 100px);
}

Multiple anchors

We learned about the anchor() function in the last section. One of the function’s quirks is that we can only declare it on inset-based properties, and all of the examples we saw show that. That might sound like a constraint of working with the function, but it’s actually what gives anchor() a superpower that anchor positioning properties don’t: we can declare it on more than one inset-based property at a time. As a result, we can set the function multiple anchors on the same target element!

Here’s one of the first examples of the anchor() function we looked at in the last section:

.target {
  top: anchor(--my-anchor bottom);
  left: anchor(--my-anchor end, 50%);
}

We’re declaring the same anchor element named --my-anchor on both the top and left inset properties. That doesn’t have to be the case. Instead, we can attach the target element to multiple anchor elements.

.anchor-1 { anchor-name: --anchor-1; }
.anchor-2 { anchor-name: --anchor-2; }
.anchor-3 { anchor-name: --anchor-3; }
.anchor-4 { anchor-name: --anchor-4; }

.target {
  position: absolute;
  inset-block-start: anchor(--anchor-1);
  inset-inline-end: anchor(--anchor-2);
  inset-block-end: anchor(--anchor-3);
  inset-inline-start: anchor(--anchor-4);
}

Or, perhaps more succintly:

.anchor-1 { anchor-name: --anchor-1; }
.anchor-2 { anchor-name: --anchor-2; }
.anchor-3 { anchor-name: --anchor-3; }
.anchor-4 { anchor-name: --anchor-4; }

.target {
  position: absolute;
  inset: anchor(--anchor-1) anchor(--anchor-2) anchor(--anchor-3) anchor(--anchor-4);
}

The following demo shows a target element attached to two