Chrome’s announcement post demonstrates how, if we were using anchor positioning, we could use anchored container queries to query the currently active fallback position (if any). They’ve provided a little demo in the post where a toggletip caret is anchored to the side of a toggletip, but if the toggletip needs to be anchored to a different side of the trigger due to lack of space, the caret is anchored to a different side as well. So in this case, anchored container queries are used to determine which position the toggletip is in, so that we can position the caret accordingly.

This is a pretty good use-case for anchored container queries, but also a great opportunity to look at how we might build toggletips in the (hopefully) near future. You’ll learn about popovers and anchor positioning, which are already baseline and will ensure that the toggletips at least work, as well as declarative anchors, ‘modern’ attr(), and corner-shape, progressive enhancements enchantments that provide a range of magical benefits.

Here’s what we’ll be making:

See the Pen Anchored container queries demo by Andy Bell (@piccalilli) on CodePen.

In Chrome you’ll see toggletip carets that flip to the appropriate side depending on the amount of space available, but in other web browsers you’ll get the toggletips without carets.

Let’s get into it!

Setting up the popover and anchor associations

We’ll be using popovers to mark up the toggletips, as that’s the semantic way to do so these days, but before we begin it’s worth mentioning that they’re implicitly anchored. However, since you might want to use anchored container queries without popovers, I’ll show you how to set up anchor associations anyway.

To set up the popover and anchor associations in a declarative but progressively enhanced way, we’ll need the following HTML markup:

<div anchor="leftButton" id="--leftPopover" popover>Toggletip</div>
<div anchor="centerButton" id="--centerPopover" popover>Toggletip</div>
<div anchor="rightButton" id="--rightPopover" popover>Toggletip</div>

<button id="leftButton" popovertarget="--leftPopover">Button</button>
<button id="centerButton" popovertarget="--centerPopover">Button</button>
<button id="rightButton" popovertarget="--rightPopover">Button</button>

The most familiar part of this is probably the popover markup. We’ve given the toggletips the popover attribute, and then an id so that each trigger can reference a popover using the popovertarget attribute. The strange part is that we’ve used custom-ident values (e.g., --leftPopover), but I’ll explain why shortly. That’s the popover functionality set up.

For the anchor positioning we’ve also given ids to the triggers, and then referenced them from anchor attributes set on the toggletips. These values don’t have to be custom idents.

However, for web browsers that don’t support the anchor attribute, we’ll need to use CSS instead, and there’s a shorter and a longer way to do that depending on whether or not modern attr() is supported.

The shorter, modern attr() way:

/* Modern attr() supported */
@supports (x: attr(x type(*))) {
  button {
    /* Reuse the name from popovertarget */
    anchor-name: attr(popovertarget type(<custom-ident>));
  }

  [popover] {
    /* Anchor to the relevant button */
    position-anchor: attr(id type(<custom-ident>));
  }
}

Basically, if modern attr() is supported, we reuse the popovertarget values of the buttons as anchor names while making it clear that we want to parse them as custom idents. After that, we match the id values of the popovers to said anchors, thus setting up the anchor positioning associations. The anchor-name and position-anchor CSS properties only accept custom idents (e.g. --leftPopover), so that’s why we're making a big fuss about them.

Next, if modern attr() isn’t supported, name each anchor manually:

/* Modern attr() not supported */
@supports not (x: attr(x type(*))) {
  /* Assign anchor name */
  #leftButton {
    anchor-name: --leftButton;
  }

  /* Anchor to button */
  #leftPopover {
    position-anchor: --leftButton;
  }

  /* And so on... */
  #centerButton {
    anchor-name: --centerButton;
  }

  #centerPopover {
    position-anchor: --centerButton;
  }

  /* And so on... */
  #rightButton {
    anchor-name: --rightButton;
  }

  #rightPopover {
    position-anchor: --rightButton;
  }
}

Once modern attr() is Baseline widely available, we can delete this block, and then once the anchor attribute is Baseline widely available, we can delete all of this CSS. You won’t even need to use custom-ident values, so --leftPopover can become leftPopover, for example.

Note: if we’d rather that the toggletips be triggered on :hover (making them tooltips instead of toggletips), we can swap popovertarget for interestfor, but note that interest invokers are only supported in Chrome 142 and above. Keep them in mind for the future!

Aligning and styling the toggletips

Like last time, I’ll drop the code right here so you can skim through it before we look at it line-by-line:

[popover] {
  position: fixed;

  /* Align to right/implied center */
  position-area: right;

  /* If no space, flip to other inline side */
  position-try: flip-inline;

  /*
    1rem of spacing between the button and
    toggletip that also flips side accordingly
  */
  margin-inline-start: 1rem;

  /* Anchor toggletip caret to this */
  anchor-name: --toggletip;

  /* Used to query this container’s fallbacks */
  container-type: anchored;

  /* Scooped corners, if supported */
  @supports (corner-shape: squircle) {
    border-radius: 3rem;
    corner-shape: squircle;
  }

  /* Normal corners, if not supported */
  @supports not (corner-shape: squircle) {
    border-radius: 1rem;
  }
}

First, we must declare position: fixed on the anchored element (in this case though, popovers already have it).

Next, we need to position the toggletip relative to the button (let’s say the center-right) using the position-area property. Now, you might think that position-area: center right is the correct declaration here, but here’s what that actually does:

As you can see, it’s overflowing the center-right tile, which is wrong but forgiving, since web browsers declare align-self: anchor-center under the hood to make it work anyway. This is declared on what’s called the Inset-Modified Containing Block (IMCB), which again is the center-right tile.

However, for reasons unknown, web browsers aren’t so forgiving when a fallback position is activated. The trick is to use position-area: right instead. By omiting the center keyword, it resolves to position-area: span-all right, which does this:

Now the toggletip does fit into the tile (IMCB). And again, it’s vertically aligned within the center of it due to align-self: anchor-center.

We can safely use position-try: flip-inline, which turns right into left whenever the toggletip overflows the viewport. Later on, anchored container queries will query whether this is happening or not.

After that, margin-inline-start: 1rem adds 1rem of spacing between the button and the toggletip at the start of the inline axis, which also flips accordingly.

anchor-name: --toggletip turns the popovers into anchors so that we can create toggletip carets and anchor them to said popovers. Normally this’d be a naming collision waiting to happen (because three different popovers are now called --toggletip, right?), but the toggletip carets will be nested inside the popovers, so they’re somewhat scoped.

And remember, we’ll be flipping the toggletip’s caret to the opposite side whenever the toggletip is flipped, and that’s what container-type: anchored is for — it’s a totally new type of container and we’ll be querying it’s fallback position to determine the correct side.

One more thing, though…

If corner-shape: squircle is supported (@supports (corner-shape: squircle)), then we use it with border-radius: 3rem to create corners that aren’t quite rounded but aren’t quite square either. If it’s not supported then we just use border-radius: 1rem. This is optional of course, but corner-shape will play a bigger role when we use it again in a moment:

/* Scooped corners, if supported */
@supports (corner-shape: squircle) {
	border-radius: 3rem;
	corner-shape: squircle;
}

/* Normal corners, if not supported */
@supports not (corner-shape: squircle) {
	border-radius: 1rem;
}

Creating and positioning the toggletip’s caret

Similar to how we anchored the toggletips to the buttons, the following code anchors the toggletip carets to the toggletips:

[popover] {
	/* Previous section code */

  /* Toggletip caret */
  &::after {
    /*
      Only create carets if anchored
      container queries are supported
    */
    @supports (container-type: anchored) {
      /* Create caret */
      content: "";

      /* Anchor to toggletip */
      position: fixed;
      position-anchor: --toggletip;

      /* Scooped carets, if supported */
      @supports (corner-shape: scoop) {
        height: 1rem;
        aspect-ratio: 1/2;
        corner-shape: scoop;
        background: inherit;
      }

      /* Normal carets, if not supported */
      @supports not (corner-shape: scoop) {
        /* Hack to create a triangle */
        width: 0;
        height: 0;
        border-top: 0.5rem solid transparent;
        border-bottom: 0.5rem solid transparent;
      }

      /* If no fallback */
      @container anchored(fallback: none) {
        /* Position caret on the left */
        position-area: left;

        /* Needed for scooped carets */
        @supports (corner-shape: scoop) {
          border-top-left-radius: 100% 50%;
          border-bottom-left-radius: 100% 50%;
        }

        /* Needed for normal carets */
        @supports not (corner-shape: scoop) {
          /* Part of the triangle hack */
          border-right: 0.5rem solid var(--toggletip-color);
        }
      }

      /* If flip-inline fallback triggered */
      @container anchored(fallback: flip-inline) {
        position-area: right;

        @supports (corner-shape: scoop) {
          border-top-right-radius: 100% 50%;
          border-bottom-right-radius: 100% 50%;
        }

        @supports not (corner-shape: scoop) {
          border-left: 0.5rem solid var(--toggletip-color);
        }
      }
    }
  }
}

First of all, the toggletip carets are CSS-generated using the ::after pseudo-element:

[popover] {
  &::after {
    /* Toggletip caret */
	}
}

Then, within that, we need to see if the web browser supports anchored container queries (if not, the toggletip carets simply aren’t generated, although the toggletips will still work):

[popover] {
  &::after {
		@supports (container-type: anchored) {
	    /*
	      Only create carets if anchored
	      container queries are supported
	    */
		}
	}
}

Within that, content: "" generates the toggletip carets (or, rather, it generates a pseudo-element with no content that we’ll style into carets).

position: fixed and position-anchor: --toggletip anchors them to the toggletips.

After that, we again leverage corner-shape to create scooped toggletips. Or, if corner-shape isn’t supported, then we use the classic border trick to create triangle-shaped carets.

We also — finally — implement those anchored container queries to position the carets to the correct side of the toggletips. When a fallback isn’t active, @container anchored(fallback: none) will match, but when a fallback is active, @container anchored(fallback: flip-inline) will match. The value of fallback simply needs to match a value of position-try:

position-try: flip-inline, in our case

/* Scooped carets, if supported */
@supports (corner-shape: scoop) {
	height: 1rem;
	aspect-ratio: 1/2;
	corner-shape: scoop; /* (Border radius is set later) */
	background: inherit;
}

/* Normal carets, if not */
@supports not (corner-shape: scoop) {
	/* Hack to create a triangle */
	width: 0;
	height: 0;
	border-block: 0.5rem solid transparent; /* (Side is set later) */
}

/* If no fallback */
@container anchored(fallback: none) {
	/* Position caret on the left */
	position-area: left;

	/* Left border radii for scooped carets */
	@supports (corner-shape: scoop) {
		border-top-left-radius: 100% 50%;
		border-bottom-left-radius: 100% 50%;
	}

	/* ‘Left’ border for normal carets */
	@supports not (corner-shape: scoop) {
		border-right: 0.5rem solid var(--toggletip-color);
	}
}

/* If flip-inline fallback triggered */
@container anchored(fallback: flip-inline) {
	position-area: right;

	/* Right border radii for scooped carets */
	@supports (corner-shape: scoop) {
		border-top-right-radius: 100% 50%;
		border-bottom-right-radius: 100% 50%;
	}

	/* ‘Right’ border for normal carets */
	@supports not (corner-shape: scoop) {
		border-left: 0.5rem solid var(--toggletip-color);
	}
}

As a reminder, here’s the final demo:

See the Pen Anchored container queries demo by Andy Bell (@piccalilli) on CodePen.

Wrapping up

Container queries are evolving beautifully, especially with the newest addition, anchored container queries. And, thanks to other modern CSS features such as the anchor attribute, ‘modern’ attr(), corner-shape, and even interest invokers, we can include all kinds of progressive enhancements to create some really awesome — in this case — toggletips.

If you want to go ahead and implement this (full code in the demo), you totally can. If something isn’t supported it’ll simply revert to something that is, and then as new features become baseline, you can very easily remove the code that’s no longer needed.

For bulleted or unordered lists, use padding to indent each list item the equivalent distance of a line height. This will allow the bullet to sit neatly in a square of white-space.

ul {
	padding-inline-start: 1lh;
}

Numbered or ordered lists which reach into double figures and beyond will require more space. Allocate this space in multiples and fractions of the line height.

The basics: choosing different kinds of lists

Unordered lists

Unordered lists are given filled discs for bullets by default. As lists are further nested, browsers apply circles. These are followed by filled squares for lists nested three or more deep.

See the Pen Lists: example 0 - default nested lists by Andy Bell (@piccalilli) on CodePen.

You can change which bullets are used through the list-style-type property with values of disc, circle and square respectively. For example, to make all unordered list items filled squares use:

ul li {
	list-style-type: square;
}

If you want to use a different symbol for a bullet you can do so by specifying it in quote marks. You’re not limited to individual characters – as well as regular glyphs, you can use words and emoji.

The -type suffix of list-style-type implies that the bullets are typographical. You can also use images for your list bullets. Link to your image using the list-style-image property.

You can position the bullet in-line with your text by using list-style-position: inside. Use outside to set it back again.

See the Pen Lists: example 1 - basic list-style-type by Andy Bell (@piccalilli) on CodePen.

ul li.point {
	list-style-type: "👉️ ";
}

ul li.tool {
	list-style-image: url(wrench.svg);
}

ul.notes li {
	list-style-type: "Note: ";
	list-style-position: inside;
}

Ordered lists

The default style for numbered or ordered lists is a decimal progression, with each number followed by a full stop. You can change the numbering system to alphabetical or Roman numerals by applying the lower-latin, upper-latin, lower-roman, upper-roman or decimal values of list-style-type. You can also select from many non-Latin numbering systems such as Greek, Devanagari, Persian and Katakana – you’ll need to use these even when the document or element has the appropriate language set.

Changing font and colour

Numbering and bullets will inherit the colour and font of your list text. While this will provide your reader with a consistent experience, you may wish to style them differently to reduce their visual impact, or otherwise distinguish them from the text.

The bullets and numbering automatically displayed by browsers are known as markers in CSS. The good news is that these are created as ::marker pseudo-elements which means you can style them directly. The bad news is that we are very limited in which styles we can apply. All you can change is the colour (not the background) and the font via any property beginning with font- such as family, weight and size. You can also animate these properties and specify directionality of the text.

Despite these limitations, being able to style the colour and font of the markers accounts for a common use case that required workarounds and extra markup in the past. For example, applying these styles directly to the markers…

ol li::marker {
	color: gray;
	font-family: sans-serif;
	font-size: 0.8em;
}

…will reduce the visual impact of your numbering by making it grey, sans-serif and slightly smaller.

See the Pen Lists: example 2 - styling using ::marker by Andy Bell (@piccalilli) on CodePen.

By default, list markers use tabular numerals, meaning the numbers all line up nicely. If you wanted a different effect you would need to add font-variant-numeric: proportional-nums to your marker styling.

You might also be tempted to make your numeric markers much larger than your list text. This can be a pleasing effect, however simply changing the font-size of your marker to 3em probably won’t achieve the result you’re hoping for:

See the Pen Lists: example 3 - changing font size using ::marker by Andy Bell (@piccalilli) on CodePen.

The gotcha is that browsers align the baseline of markers with that of the first line of the list item text. Therefore a large list item number will always stick up above the list item text. And because we can’t apply any positioning or layout properties directly to the marker there’s not much you can do about it, although there are alternatives which we’ll come to later.

Generating your own marker content

You can customise the generated content of the marker as it also takes the content property, like this:

ul li::marker {
	/* make all the bullets pointing hand emoji */
  content: "👉️ ";
}

ol li::marker {
	/* follow each number by a parenthesis instead of a full stop */
  content: counter(list-item) ") ";
}

See the Pen Lists: example 4 - generated content in ::marker by Andy Bell (@piccalilli) on CodePen.

Generating content for markers is supported by Chromium and Firefox, but not by WebKit (Safari), with no support in sight at the time of writing. Safari falls back to regular bullets or numbering which may, or may not, be acceptable to you depending on whether you consider your styling a progressive enhancement rather than crucial to the meaning of your content.

So what is ::marker good for? It’s definitely the way to go if you want to change just the colour or font of your list markers. Anything more and you’ll need a different technique. Before we get on to those we need to talk about symbols and counters.

So far we have been defining what the bullets in an entire list should look like, that is to say we’re using the same symbols for all list items at the same level of nesting. However it is also possible to define a sequence of symbols for your bullets. There are a couple of ways to do this. The first is with the symbols() function, which you can use as a value of the list-style property. For example, you could specify the classic sequence of symbols for footnotes:

ol {
	list-style: symbols("*" "†" "‡" "§");
}

In this case the symbols automatically double up when the end of your specified sequence is reached. You can add the cyclic keyword to prevent this. The default behaviour is symbolic.

ul {
	list-style: symbols(cyclic "🌑" "🌓" "🌕" "🌗");
}

You can also specify that your symbols sequence is numeric like decimals …7 8 9 10 11… or alphabetic like …a b c aa ab ac ba…, or use fixed to revert to default numbering once your custom symbols run out – useful if you’re specifying a sequence like ① ②…⑧ ⑨.

However, the symbols() function is only supported in Firefox, with no interest from Webkit or Chromium at the time of writing. In theory you can also specify a sequence of images, but this is not supported in any browser.

The CSS spec says The symbols() function allows a counter style to be defined inline in a property value, for when a style is used only once in a stylesheet and defining a full @counter-style rule would be overkill.. And this brings us to some good news.

Defining your own numbering sequence

The @counter-style rule enables you to further specify exactly what symbols or text appear in your list markers, and in what order or combination. You can use it to replicate all the symbols() and ::marker content functionality we’ve seen so far, and cross-browser is support is good – it became Baseline Newly Available in September 2023.

This is how to use @counter-style to achieve the symbols() examples we looked at earlier. This will work across all modern browsers today:

@counter-style --footnotes {
  system: symbolic;
  symbols: '*' † ‡ §;
  suffix: " ";
}

@counter-style --moons {
  system: cyclic;
  symbols: 🌑 🌓 🌕 🌗;
  suffix: " ";
}

Which you apply to your lists using the list-style property:

ol.footnotes { 	list-style: --footnotes; }
ul.moons { list-style: --moons; }

See the Pen Lists: example 7 - @counter-style demo by Andy Bell (@piccalilli) on CodePen.

Similarly one of the marker examples attempted to use a 👉️ for all its bullets. You can achieve that effect cross-browser like this:

@counter-style --point {
  system: cyclic;
  symbols: 👉️;
  suffix: " ";
}

See the Pen Lists: example 8 - @counter-style example with pointing hand bullets by Andy Bell (@piccalilli) on CodePen.

These counter style examples consist of four parts. The first is a name for the style, such as --point. You can call the counter styles pretty much what you want. You don’t need to prefix them with -- although I find it good practise to do so in order to be consistent with naming custom properties. The other parts of the rule are:

• system which sets the algorithm used for how the counter works. This takes the same keywords as the symbols() function described earlier, plus additive and extends which we’ll come to later.
• symbols is a space separated list of numbers or bullets (in theory this can also take images but there’s no support at the time of writing). Some characters need to be quoted such as * – to be safe you could put all the characters inside quotes, but generally you don’t need to.
• suffix is the character or characters inserted after the counter (a simple space in our examples so far).

For completeness, counter style rules also take the following descriptors, some of which are more niche than others:

• prefix is the character or characters inserted before the counter
• negative sets the characters before and after a negative counter value. For example, specifying negative: "(" ")" will wrap negative counters in parentheses, which is sometimes used in financial contexts, like “(2) (1) 0 1 2 3…”. It’s fair to say there are very few use cases for negatively numbered ordered lists, however this is still a good opportunity to specify a proper minus symbol instead of a hyphen, just in case: negative: "−".
• pad gives you a fixed-width style of numbering by repeating a character before the counter such that all counters are the same width. In reality this means zero-padded decimal numbering. So if you know that your ordered list goes up to less than a thousand, you can specify pad: 3 "0" to ensure that all counters are (at least) 3 digits wide. This will cause 1 to be shown as "001", 20 as "020", 300 as "300", 4000 as "4000", and -5 as "-05" (still three characters wide).
• range enables you apply counter styling to specific ranges in the ordered list. For example adding range: 3 5, 20 infinite will only apply styles to list items with counters 3,4 ,5 and anything 20 and above. All other list items will get the default style of numbering.
• speak-as describes how assistive technologies should synthesise the spoken form of a counter. Our earlier example had symbols: 🌑 🌓 🌕 🌗. To prevent the browser introducing each list item with something like ‘first quarter moon’, you could set speak-as: bullets so they are introduced like a normal unordered list. See the spec for more options. Only Safari supports this at the moment but it’s a good candidate for progressive enhancement.

For more examples and creative uses of @counter-style see Geoff Graham’s CSS Tricks article.

Thinking back to our other marker example, we followed the number by a closing parenthesis instead of a full stop. This is a perfect use case for the extends system. Instead of starting from scratch and working out how to define decimal counting in a counter style, we can ‘extend’ the existing decimal style. You might like to think of extends as meaning ‘modifies’. Here’s how:

@counter-style --decimalparen {
  system: extends decimal;
  suffix: ") ";
}

See the Pen Lists: example 9 - @counter-style demo of 'extends' system by Andy Bell (@piccalilli) on CodePen.

You can’t include a symbols descriptor when extending a counter style as that would imply you’re defining a brand new style. You can extend any counter system from the standard list-types as well as any named custom counter styles.

The space character in the suffixed ") " exposes a slight inconsistency between browsers. If you take the space away you’ll see that Chrome and Firefox position the marker flush against the list item text. However Safari always introduces a gap, which you can’t remove. Most of the time this difference is subtle and inconsequential, but once you start heavily customising your markers it can be more obvious. This is particularly true if you’re increasing the font size of your markers, but as we saw earlier that brought its own problem with the marker being aligned to the first line of text.

Creating your own marker box

The only solution to all these inconveniences is to remove the ::marker pseudo element and create your own in such a way that you can style it to your specific purposes.

Firstly remove the marker pseudo element by applying list-style:none to your list:

ol {
	list-style: none;
}

Having done that, Safari will no longer announce your list to assistive software. To rectify this, tell browsers this really is a list by applying an ARIA role:

<ol role="list">
	<li>First item.
	  <ol role="list">
			<li>Nested item.</li>
		</ol>
	</li>
	<li>Second item.</li>
</ol>

Now create your own placeholder for the counter by creating ::before pseudo elements and moving them into the margin. Then use generated content to display the counter using the counter() function.

ol[role='list'] li::before {
	display:inline-block;
	width:4ch;
	padding-inline-end:1ch;
	margin-inline-start:-5ch;
	text-align:right;
	font-variant-numeric: tabular-nums; /* make the numbers line up nicely */

	content: counter(list-item) ".";
}

See the Pen Lists: example 10 - generating custom list marker elements using li::before by Andy Bell (@piccalilli) on CodePen.

The counter() function takes a counter name, which you can specify. In this case we’ve used list-item which is a special name reserved as an implicit counter for the list being styled. It outputs the position of the list item.

You can also output the position of all the list numbers in nested sequence, separated by a character or string. To do this use the counters() function:

ol[role='list'] li::before {
	content: counters(list-item,".") ":";
}

See the Pen Lists: example 11 - demo of counters() function for nested numbering by Andy Bell (@piccalilli) on CodePen.

If you want your list to start at 1 and increment by 1 each time, you don’t need to do anything else provided you use list-item as your counter name. Otherwise you can reset or create a new counter, set its starting point (the default is 0) and increment by a defined amount for each list item:

ol[role='list'].mylist {
	list-style: none;
	counter-reset: --myList 3;
}

ol[role='list'].mylist li {
	counter-increment: --myList 2;
}

ol[role='list'].mylist li::before {
	content: counter(--myList) ". ";
}

See the Pen Lists: example 12 - counter reset and increment by Andy Bell (@piccalilli) on CodePen.

You can use counter-increment with any selector meaning you can just as easily number headings in sequence:

h2 {
	counter-increment: --h2;
}

h2::before {
	content: counter(--h2) ". ";
}

See the Pen Lists: example 13 - automatically numbering headings by Andy Bell (@piccalilli) on CodePen.

If all you want to do is set the start number for a list or adjust an item’s value, you don’t need to use CSS, you can do it in HTML using start and value. If you want to have the list items count down instead of up you’ll need to specify that in HTML with a reverse attribute:

<ol start="42">
  <li>First item starts at 42</li>
  <li>This one is then 43</li>
  <li>And we end on 44</li>
</ol>

<ol>
  <li>This is number 1</li>
  <li value="42">This is number 42</li>
  <li>It follows that this is 43</li>
</ol>

<ol reversed start="44">
  <li>Counting down from 44</li>
  <li>Now we're at 43</li>
  <li>The final answer.</li>
</ol>

See the Pen Lists: example 14 - HTML start, value and reversed by Andy Bell (@piccalilli) on CodePen.

Tying it all together

Finally let’s use some of what we’ve learned to create this list:

See the Pen Lists: example 15 - fancy list markers by Andy Bell (@piccalilli) on CodePen.

Here’s the full CSS which we’ll walk through afterwards:

ul[role='list'] {
  list-style: none;
  max-inline-size:23em;
  padding-inline-start:2.5em;
  line-height:1.25em;
}

ul[role='list'] li {
  margin-block-end:1lh;
  min-block-size: 2lh;
  position:relative;
  text-box: trim-start cap alphabetic;
}

@counter-style --fleurons {
  system: cyclic;
  symbols: ❦ ✾ ✤ ❈ ✺ ❥;
  suffix: "";
  speak-as: bullets;
}

ul[role='list'] li::before {
  position:absolute;
  inset-block-start: 0;
  inset-inline-start: -1.25em;
  inline-size:1em;
  text-box: trim-start cap alphabetic;
  text-align:end;
  font-size:2lh;
  line-height:1;
  font-weight:bold;
  color: hsl(3, 70%, 55%);
  content: counter(list-item, --fleurons);
}

Breakdown

Looking at each rule individually:

ul[role='list'] {
  list-style: none;
  max-inline-size:23em;
  padding-inline-start:2.5em;
  line-height:1.25em;
}

We start by removing the default bullets, remembering to tell assistive software the list is still a list. We then set enough padding next to the list to accommodate our fancy new bullets.

ul[role='list'] li {
  margin-block-end:1lh;
  min-block-size: 2lh;
  position:relative;
  text-box: trim-start cap alphabetic;
}

Next we address the list items themselves, spacing them apart using the list’s line-height to stick to a vertical rhythm. We give each item a minimum height to fit a bullet symbol, and set to relative positioning in preparation for our custom list markers. Finally we trim the text to the top of the capital letters to help us align our bullets consistently.

@counter-style --fleurons {
  system: cyclic;
  symbols: ❦ ✾ ✤ ❈ ✺ ❥;
  suffix: "";
  speak-as: bullets;
}

We now define a sequence of fancy Unicode symbols to use as bullets. These will cycle round if we end up with more than six list items. We make sure they are announced as ‘bullet’ rather than ‘rotated heavy black heart’, etc.

ul[role='list'] li::before {
  position:absolute;
  inset-block-start: 0;
  inset-inline-start: -1.25em;
  inline-size:1em;
  text-box: trim-start cap alphabetic;
  text-align:end;
  font-size:2lh;
  line-height:1;
  font-weight:bold;
  color: hsl(3, 70%, 55%);
  content: counter(list-item, --fleurons);
}

Finally we create pseudo elements before each list item and absolutely position them off to the side, leaving a 0.25em gap. We want the bullets to nicely span two lines of text, so we make the font size 2lh, remove any half-leading by setting the line height to 1, and trim the text box to the top of the capitals so it aligns with our list text. Finally we make the bullet bold and red, and write it to the page using generated content by way of the list-item implicit counter and our --fleurons counter style.

There could be a case for using anchor positioning here, however good old fashioned absolute positioning has 100% support and provides a very simple solution to the task at hand.

In summary

Phew. Modern CSS enables you to do so much with lists it’s sometimes hard to know where to start, especially as browser support is not complete. Here’s a summary of which properties you should turn to for different use cases.

Sources and further reading

I am indebted to the following articles, in no particular order:

• https://kizu.dev/list-item-counter/
• https://moderncss.dev/totally-custom-list-styles/
• https://hadrysmateusz.com/blog/css-list-styling
• https://web.dev/articles/css-marker-pseudo-element
• https://css-tricks.com/some-things-you-might-not-know-about-custom-counter-styles/
• https://www.smashingmagazine.com/2019/07/css-lists-markers-counters/

Specifications:

• https://drafts.csswg.org/css-counter-styles/
• https://drafts.csswg.org/css-lists/
• https://html.spec.whatwg.org/multipage/grouping-content.html#the-ol-element

Initially I thought this would be helpful with prototyping because I could choose a single color for the background, and the foreground color could automatically update to become at least readable. This reduces the number of decisions I need to make and allows for faster development.

You can probably imagine how this might be helpful in production as well because dozens of design tokens meant to describe the presentation of an experience could be reduced if some of these decisions happened behind the scenes. The colors that truly encompass the brand and its expression could be carefully chosen, while other supporting colors could “just work”.

Browser engineers have been working towards a solution for this in CSS called contrast-color(). Here’s what that will look like:

body {
	background: black;
	color: contrast-color(black);
}

The color used for the background is passed as an argument in the CSS contrast-color() function to produce either black or white. Unfortunately, this isn’t available in all browsers at the time of this writing, so instead, folks across the web have been either curating both background and foreground colors separately or are required to pass their color choices through some preprocessor to output appropriate contrasting colors.

However, there’s been other advances in CSS that we might consider helping us achieve the features of contrast-color() today in all browsers.

The earliest attempt of getting this behavior that I can remember is a post on CSS-Tricks by Josh Bader. His approach required the person to break out the red, green, and blue channels of the color to then perform some math to get the contrasting color.

:root {
  --red: 28;
  --green: 150;
  --blue: 130;

  --accessible-color: calc(
    (
      (
        (
          (var(--red) * 299) +
          (var(--green) * 587) +
          (var(--blue) * 114)
        ) / 1000
      ) - 128
    ) * -1000
  );
}

.button {
  color:
    rgb(
      var(--accessible-color),
      var(--accessible-color),
      var(--accessible-color)
    );
  background-color:
    rgb(
      var(--red),
      var(--green),
      var(--blue)
    );
}

The resulting --accessible-color is a number for each channel that would surpass the boundaries of the rgb() color function causing the resulting color to be either black or white. In other words, a color written as rgb(-10, -10, -10) is not invalid, it is black.

The problem here is that you’d need to break out your colors into separate channels for every color that you use. While this might be less decision making than before, it’s also more maintenance and naming as each color would need some channel identifier at the end, such as, button-background-red. This initial naming could even be confusing itself. While we intend for the value of this variable to be the number than represents the red channel for the button background, others looking at this could mistake this as the color to present a red button.

However, this approach did give me a new idea. In order to figure out the contrasting color for a given color, we need to get the numeric value for channels and manipulate them somehow. Luckily there’s a new feature within the CSS color specification that does exactly this: Relative Color Syntax.

body {
	background-color: rgb(from red r g b);
}

The result of the above code wouldn’t display anything special; the page would have a simple red background color. Where this gets interesting is the r, g, and b values. These are numbers that present the channels of red, green, and blue respectively for the given red color. This means we could use the given numbers to create a new color. For example, let’s make the red lighter using LCH.

body {
	background-color: lch(from red calc(l + 20) c h);
}

Relative color syntax can break out the channels for many color spaces and many of the color functions we’ve been using for years include the from keyword in their syntax. This means than we can now easily add an alpha channel amount to a given color.

body {
	background-color: rgb(from red r g b / .5);
}

Yep, we don’t need to explicitly use the rgba function here to include the alpha channel. This will add the .5 opacity to the red for the background with ease.

So now that we have this system, we should be able to use the same calculation from Josh’s article within the color function. Buckle up, it’s a bit of a doosie!

@property --channel {
  syntax: "*";
  inherits: false;
  initial-value: calc((((r * .299) + (g * .587) + (b * .114)) - 128) * -1000);
}

body {
	--color: black;
	--contrast-color: rgb(from var(--color)
    var(--channel)
    var(--channel)
    var(--channel)
  );
  background: var(--color);
  color: var(--contrast-color);
}

See the Pen Using @property to create reusable color-contrast channel by Andy Bell (@piccalilli) on CodePen.

Okay, this is a lot so let’s break it down. You’ll see I’m using the @property syntax to define a calc() function. I’m using @property to keep the gnarly formula away from the CSS declarations in use. In this function I’ve replicated the math happening in the original approach with some small changes.

For example, instead of dividing the result of the addition by 1000, we update the numbers to have been each divided by 1000. We make this a custom property so the declaration can be reused across channels without duplicating the mess of operations. From here, the use is similar to what Josh had done before except with the relative color syntax to pull out the individual channels automatically.

When I originally posted this back in June 2025, Matt Ström-Awn made some quick but important improvements. He noted that WCAG contrast algorithm uses a color’s XYZ color space, specifically it’s Y value, to determine the level of acceptable contrast. This means that we can compute the contrasting color by using the color() function and setting the color space to XYZ. Then we force each channel to be computed based on the Y value. Here’s his implementation:

body {
	color: color(from var(--color) xyz
		round(up, min(1, max(0, 0.18 - y)))
		round(up, min(1, max(0, 0.18 - y)))
		round(up, min(1, max(0, 0.18 - y)))
	);
}

See the Pen Using Matt Ström-Awn's approach for CSS color contrast by Andy Bell (@piccalilli) on CodePen.

The .18 number comes directly from the WCAG contrast ratio formula (L1 + 0.05) / (L2 + 0.05). To find the luminance where contrast against white equals contrast against black, you set them equal and solve for the luminance. Y = (√21 - 1) / 20 ≈ 0.1791.

body {
	/* ≈ 0.1791 */
	--y: calc((pow(21, .5) - 1) / 20); 
}

In writing this article, my research led me to a post by Lea Verou, Ph.D who explores a similar approach about a year earlier where she says a good threshold for flipping to black text is when Y > 0.36.

body {
	color: color(from var(--color) xyz-d65
		clamp(0, (.36 / y - 1) * infinity, 1)
		clamp(0, (.36 / y - 1) * infinity, 1)
		clamp(0, (.36 / y - 1) * infinity, 1)
	);
}

See the Pen Using Lea Verou's approach for CSS color contrast by Andy Bell (@piccalilli) on CodePen.

There’s even further consideration for lower contrast mid luminances where fonts should be adjusted. Unfortunately, we cannot pull out the y from these functions to use in anything outside of the relative color syntax. Otherwise, we could use the y to affect things like font-size or font-weight to improve readability further.

One of the gotchas that I found while using these formulas is that they don’t account for the possibility of an alpha channel being included. Certainly, if the alpha channel number is significantly large, then the color isn’t really meant to contribute to the contrast algorithm. In other words, a color like rgb(255 0 0 / .9) is barely red and the text color that might appear on top should really be compared to another background color that appears truly underneath.

In the case where the alpha channel is not significant, I still want to ensure that the text does not receive the incoming alpha channel value. So, I recommend explicitly adding a / 1 to the end of the statement. This will cause the resulting foreground color to be opaque which is important for readability.

body {
	color: color(from var(--color) xyz
		clamp(0, (.36 / y - 1) * infinity, 1)
		clamp(0, (.36 / y - 1) * infinity, 1)
		clamp(0, (.36 / y - 1) * infinity, 1)
		/ 1 /* Add for opaque color */
	);
}

As you might imagine, supplying values that aren’t a single color, like a gradient, will fail this computation. However, a color that is determined through color-mix() may also fail in the relative color syntax. This means that it’s best to provide simple color values into the function where possible to avoid the function from failing. When the function fails, the color statement will be invalid and a color you may have not been expecting might be rendered instead.

On the other hand, this doesn’t mean you couldn’t send the resulting color into a color-mix() to tint in a certain direction.

body {
	background-color: var(--color);
	--contrast-color: color(from var(--color) xyz
		clamp(0, (.36 / y - 1) * infinity, 1)
		clamp(0, (.36 / y - 1) * infinity, 1)
		clamp(0, (.36 / y - 1) * infinity, 1)
		/ 1
	);
	color: color-mix(in srgb, var(--contrast-color), var(--color) 20%);
}

See the Pen Using color-mix() with CSS color contrast by Andy Bell (@piccalilli) on CodePen.

In this example, we compute the contrast color with our latest formula and then mix that with the background slightly to produce the final foreground color. Importantly, this reduces the guarantee that the final foreground color will have sufficient contrast for certain given colors. So, choosing colors that have high saturation, and / or significant lightness would work best.

While we wait for contrast-color() to arrive in all browsers, these CSS-only approaches give us a practical way forward today. By leveraging relative color syntax and the XYZ color space, we can generate manageable contrasting colors without curating separate values. The formula isn’t perfect but for the majority of single-color backgrounds, it delivers what we’ve been hoping for: text that “just works”. As browser support continues to improve and these techniques become more refined, we’re one step closer to reducing the decision fatigue that comes with building for the web.

<!-- ❌ Never do this! -->
<button type="button">
  <a href="/path/to/resource/">
    Save as favorite
  </a>
</button>

There are a few reasons not to do this, but the most important reasons is it can prevent people from using your service just by virtue of the way they use to interact with the web.

In spite of this fact, nested interactive controls are a pattern I see with regularity. I chalk this fact up to:

1. A general lack of awareness or education about web accessibility,
2. A tendency to skip accessibility reviews and save fixes for some undetermined future state, and also
3. Newer web experiences becoming more “app-like.”

By app-like, I mean things like seamless transitions between pages, less overall page content, and larger, touch-friendly interactive areas.

And app-like experiences on the web isn’t a bad thing! It’s more that when we borrow the affordances of mobile apps we must also do so in a way that honors the conventions of the web platform.

An example

Here’s a UI pattern I was working on recently:

It is a list of items, with each item containing both

1. A primary action (blue), and
2. One or more secondary actions (pink).

Here, the primary action was specified to apply to the entire list item row, minus the space the secondary actions took up.

This means you can click both the primary action itself, and all of its surrounding area, minus the space reserved for secondary actions.

The idea being it would make it easier and faster for people to activate the primary action. This ease of activation is also done without sacrificing the ability to use secondary actions.

Avoiding nesting interactive elements

We can’t nest interactive controls on the web. So, this underlying HTML structure for our component would be a non-starter:

<!-- ❌ Again, don't do this -->
<ul>
  <li>
    <a href="/path/to/resource/">
      Primary action
      <button type="button">
        Secondary action
      </button>
     </a>
  </li>
</ul>

We can make this design work in such a way that both honors the designed intent and also does not nest interactive controls.

The secret to this approach? Adapting our very own Andy Bell’s semantic breakout button technique.

The gist of the technique is this:

1. You can use position: static, plus an absolutely-positioned ::before pseudo-element declaration to extend the clickable area of an interactive element to take up the entire height and width of the viewport.
2. You then use a position: relative declaration to “clamp” the clickable area to a parent element.
3. Finally, you increase the z-index value of other interactive elements to ensure they “float” over the rest of the interactive area and are clickable.

Here’s a short comic of how it works, if you’re more of a visually-oriented thinker:

We can then build from this, combining it with things like :focus-within and :focus-visible to create the appearance of nested interactive controls without actually having to do so in the DOM.

Putting it into practice

Without further ado, here’s a CodePen of the final result:

See the Pen Accessible faux-nested interactive controls by Andy Bell (@piccalilli) on CodePen.

Now, let’s break it down:

Structure

Container

The total list of items is contained within an unordered list. Each item within the list is contained with a li element. This enables assistive technology to:

• Know that it is a list,
• Enumerate how many items are in the list, and
• Announce which list item is currently being read through.

Primary content area

This is a div placed within the parent li element, and it is used to house the main action, as well as supplemental content. And placing div elements within a li is totally a thing you can do! HTML is pretty flexible, and it’s valid markup.

Secondary content area

This is another div placed within the parent li element. It is used to house the secondary action(s).

Leading visual

This is a child element of the primary content area, and provides an area where we can insert an icon or graphic to help with quick visual scanning. In our example, it provides a photo of the lunch special you can order.

Primary action

This is also a child element of the primary content area. In our example, the primary action is a link that allows you to read up on more detail about the lunch special.

This is the main thing we want people to click on. It will be targeted in CSS to extend its interactive area to the boundaries of the parent li element, using the breakout technique discussed previously.

We also use a heading element to wrap the text of the primary action. This allows people who use screen readers to quickly scan the page to know its overall makeup when navigating by heading.

From there, people can then use other navigation techniques to dial in when they want to learn more about the content the heading introduces.

Secondary actions

These are children of the secondary content area.

More than one secondary action can be added to the secondary content area, provided the actions are not nested inside one another in the DOM.

There is also no upper limit to the number of secondary actions you can use, either. In our example, the secondary actions are two buttons that allow you to:

1. Favorite an item in the list, and also
2. Quickly add an item to your shopping cart.

It is also good practice to disambiguate the accessible names of your secondary actions. I like a “verb noun” pattern, so for our example it’s “Favorite: Sashimi Lunch” and “Add to cart: Salmon and Avocado Maki.”

Styling

Grids

CSS grid does the heavy lifting for placing content. We’re using named grid areas to both:

1. Place items within the primary and secondary content areas, and then
2. Lay content out within the primary content area.

Named grid areas is a technique that I’ve found helpful for future maintenance efforts.

Other people working with the component may be less familiar with both CSS and grid-based declarations. Because of this, a visual arrangement of the layout in code that uses easy-to-understand grid area names may make it less confusing to parse — especially when your design needs to be responsive.

The use of named grid areas also potentially lowers the chance someone does something unintended. This is really important for a component like this, where we rely on z-index to ensure secondary content remains interactable.

Container queries

Speaking of making things responsive, we’re using container queries to adjust the layout so it adapts to smaller horizontal surface area without creating horizontal overflow.

The cool bit about using container queries instead of more traditional media queries is that it creates more self-contained and self-sufficient components. Here, we know that the component will adapt to whatever container it is placed in, regardless of the container’s available horizontal width.

Primary action click area

The semantic breakout styling is applied to .list-item-primary-action — the primary action.

The clickable area is then constrained by .list-item, the parent list item. This means that the actual interactive area is the same size as the entire list item’s computed size.

Secondary action ‘clickability’

The secondary actions are elevated above the primary action via a z-index declaration to ensure clicks and taps can successfully be intercepted.

We use calc(), Custom Properties, and :where() to create some defensive design here:

• The z-index of secondary actions is set to always be one number higher than the z-index of its parent list item.
• The parent list item‘s z-index is, in turn, scoped to the component’s parent class.

This approach helps to prevent stacking context accidents by ensuring that secondary actions will always be clickable regardless of what z-index value is used — or updated to use.

We then use :where() to target every possible interactive element you can declare in HTML and also apply the incremented z-index  treatment. This helps ensure this component is future-proof, which is important given both:

• The relative rarity of the semantic breakout technique, and
• The need to ensure new secondary actions stay intractable.

A tangent about accessible name length

An accessible name is the text value supplied to an interactive element. The preferred way to do this is to use a string in between the opening and closing tags of a HTML element:

<!-- This button has an accessible name of "Print recipe" -->
<button type="button">
  Print recipe
</button>

It is considered good practice to have your accessible names be both concise and descriptive. So, an accessible name of “Print recipe” is far more desirable than something like, “Send this recipe to your printer so you can take it into your kitchen.”

Interactive elements that contain multiple child elements with a lot of text content can inadvertently have a really long accessible name. An example of this is a block-level anchor link, say for a card component:

<a class="card-link" href="/path/to/resource/">
  <div class="card">
    <img alt="A Nintendo Switch 2 placed on a Kirby-shaped pillow." class="card-hero" src="/path/to/image.png" />
    <h3 class="card-title">
      The best gift ideas for new college students 
    </h3>
    <p class="card-description">
      Whether it is a new game console or a set of smart appliances, these items can make great gifts for your special someone!
    </p>
    <ul class="card-tags">
      <li class="card-tag">
        Trending
      </li>
      <li class="card-tag">
        Hot
      </li>
      <li class="card-tag">
        Gift Ideas
      </li>
    </ul>
  </div>
</a>

The entire card component is wrapped in an anchor element. Because of this, all its text content gets “flattened” and turned into one long accessible name.

This flattening will create an assistive technology announcement along the lines of:

A Nintendo Switch 2 placed on a Kirby-shaped pillow, graphic. The best gift ideas for new college students, heading level 3. Whether it is a new game console or a set of smart appliances, these items can make great gifts for your special someone! List, bullet Trending, bullet Hot Gift Ideas. Link.

This announcement is a lot of information to parse if you’re using a screen reader, which is tedious at best and confusing at worst. So, why do I bring this up here?

Well, the semantic breakout button technique also works wonderfully in situations like this, where we want a more concise accessible name without sacrificing the increased click area size. This helps guarantee an equivalency of experience, in that the card titles can be quickly skimmed to see if they’re of interest — both visually and not.

For our card example, we could move the anchor element inside of the card title, then extend it‘a interactive area out to cover the whole card using an application of the semantic breakout technique that targets the parent .card class.

The entire card would remain clickable, but this update would create a far less verbose assistive technology announcement for the primary link, which will be something along the lines of:

The best gift ideas for new college students. Link.

The other bit worth knowing is that use of this technique does not impede the ability of a person using a screen reader to explore the rest of the card’s content.

Using the semantic breakout technique makes it so the card content will be read out the same expected way it reads other static DOM content. That’s a good thing!

Another tangent about usability considerations

Faux-nested interactive controls run the risk of accidental activation of the wrong thing, so exercise caution when using them.

Consider things like:

• In-the-moment distractions,
• Layout shifting,
• Low vision,
• Hand tremors,
• Assistive technology such as eye-tracking,
• etc.

Accidentally clicking the wrong thing just by virtue of circumstance isn’t great for anyone involved.

Because of this, caution should be used when deciding to use this technique. Be especially careful when it comes to irrevocable or destructive actions.

It’s considered good practice to provide a secondary “Are you sure?” confirmation step for this situation, regardless of how the UI looks.

A third tangent about progressive enhancement

The only JavaScript we’re using in the CodePen demo is a small piece of logic that gives you feedback that you successfully activated a primary action.

We’re still left with something functional when JavaScript, images, or styles fail to load: A list of items that contain links.

This is pretty helpful, especially in less-than-ideal circumstances.

Wrapping up

Modern CSS lets you have it all: resilient, adaptable, fault-tolerant experiences that recreate the affordances of contemporary app-like experiences without sacrificing accessibility.

Considered and thoughtful applications of CSS — like Andy Bell’s semantic breakout button technique — can mesh harmoniously with newer features to create all sorts of new and exciting experiences.

When you call document.startViewTransition(), the browser creates pseudo-elements (::view-transition-old() and ::view-transition-new()) that represent the before and after states of your content. The browser then animates between these snapshots, creating smooth visual transitions. You can read more on that here.

I spent more time than I'd like to admit debugging view transitions blinks before understanding what was happening. The API seemed straightforward enough, but my transitions kept flashing. Here's what I learned, so you don't have to repeat my mistakes.

Beware, it blinks!

You've set up view transitions, you click, and… blink. Instead of a smooth morph between states, you get a brief flicker where content disappears and reappears abruptly. Sometimes the transition completes successfully, but then the old content briefly flashes before the new content settles. The flash can be subtle or obvious, but once you notice it, you can't unsee it. This typically occurs in tab interfaces, modals, and other components where content is shown or hidden dynamically.

The blink can also happen when the transition completes instantly rather than animating smoothly. You might see the old content vanish, followed by the new content appearing without any intermediate animation frames. What you expected was a smooth morph; what you got was an abrupt swap.

But why does it blink?

The browser needs to correlate elements between the old and new states using the view-transition-name CSS property. When an element in the old DOM state has the same view-transition-name as an element in the new DOM state, the browser creates a smooth animation between them.

The blink occurs when this correlation fails, resulting in the browser falling back to a cross-fade animation. Common causes include:

• The old element doesn't have a view-transition-name assigned before the transition starts.
• Multiple elements share the same view-transition-name (each must be unique.)
• The element is hidden via CSS (such as opacity: 0 and display: none) rather than being removed from the DOM.
• The view-transition-name is removed or changed at the wrong time.

When correlation fails, the browser has no reference point for creating the transition between states. Instead of smoothly morphing between the correlated element’s state, it falls back to a default cross-fade of the entire viewport. This appears as a blink because no smooth element-to-element morphing occurs; the browser just swaps between the two viewport states.

A tabbed interface example

Tabbed interfaces commonly suffer from the blink because they typically use CSS to toggle visibility between panels rather than manipulating the DOM directly. This pattern breaks the element correlation that view transitions require.

The broken version

Let me show you exactly how I broke it first. Learning from mistakes is more instructive than pretending I got everything right on the first try.

See the Pen Tabs - View Transitions - Old by Andy Bell (@piccalilli) on CodePen.

The problematic pattern uses position: absolute for all panels and toggles the active class:

function switchToTab(targetTabId) {
  withViewTransition(() => {
    // Remove active from all panels
    tabPanels.forEach(panel => {
      panel.classList.remove('active');
      panel.style.viewTransitionName = 'none'; // Trying to be clever... (spoiler: doesn't work)
    });

    // Add active to target panel
    const targetPanel = document.getElementById(targetTabId);
    targetPanel.classList.add('active');
    targetPanel.style.viewTransitionName = 'active-tab'; // Only new state identified
  });
}

With CSS like:

.tab-panel {
  position: absolute;
  opacity: 0; /* All panels exist, just hidden */
  pointer-events: none;
}

.tab-panel.active {
  opacity: 1; /* Only changes visibility */
  pointer-events: auto;
}

This approach fails because:

1. All panels exist in the DOM simultaneously with only visibility differences.
2. Only the new active panel receives a view-transition-name, leaving the browser unable to identify which old panel to transition from.
3. Setting viewTransitionName = 'none' explicitly breaks the correlation. Critically, attempting to remove the transition name inside the callback is too late, as the browser's snapshot of the "old" state has already been taken.

When the transition runs, the browser cannot determine which element in the old state corresponds to which element in the new state. The result is an instant swap rather than a smooth animation.

The working version

Here's the pattern that actually works:

See the Pen Tabs - View Transitions by Andy Bell (@piccalilli) on CodePen.

The working solution performs true DOM manipulation:

function switchToTab(targetTabId) {
  const currentPanel = tabContent.querySelector('.tab-panel');
  const currentButton = document.querySelector('.tab-button.active');
  const targetButton = document.querySelector(`[data-tab="${targetTabId}"]`);

if (hasViewTransitions && currentPanel) {
    // KEY: Assign view-transition-name to current panel BEFORE transition
    currentPanel.style.setProperty('view-transition-name', 'active-tab');

    const transition = document.startViewTransition(() => {
      // Update button states (animates the indicator)
      currentButton.classList.remove('active');
      targetButton.classList.add('active');

      // KEY: True DOM manipulation - remove old, create new
      tabContent.innerHTML = ''; // Removes all child elements
      const newPanel = createTabPanel(targetTabId);
      newPanel.style.setProperty('view-transition-name', 'active-tab');
      tabContent.appendChild(newPanel);
    });

    // KEY: Clean up after transition completes
    transition.finished.then(() => {
      const panel = tabContent.querySelector('.tab-panel');
      if (panel) {
        panel.style.removeProperty('view-transition-name');
      }
    });
  }
}

This approach succeeds because:

1. The current panel is identified with view-transition-name before the transition callback executes
2. The old panel is completely removed from the DOM
3. A new panel is created and assigned the same view-transition-name
4. The browser can now correlate the old and new elements, creating a smooth animation
5. Cleanup removes the transition name to prevent conflicts

The tab indicator uses a separate view-transition-name for independent animation:

.tab-button.active::after {
  content: '';
  position: absolute;
  bottom: -1px;
  left: 0;
  width: 100%;
  height: 3px;
  background: #007bff;
  view-transition-name: tab-indicator;
}

This component separation allows the indicator to slide smoothly while the content transitions independently. Note that the indicator uses a static transition name in CSS because it's always present, just moving between buttons. The content uses dynamic naming in JavaScript because panels are created and destroyed with each transition.

Universal principles for smooth transitions

The tabbed interface example demonstrate a key pattern: it solves the core problem by creating and destroying elements. This strategy works because it gives the browser clear before-and-after states. The following principles extract what makes this pattern successful and apply them to any component, regardless of whether you are swapping elements or dynamically managing a single persistent element.

Don't mix the old with the new

Each view-transition-name must be unique per page at any given time. Having multiple elements with the same transition name creates ambiguity, and the browser cannot determine which elements to correlate.

When transitioning between states, ensure only one element has a specific view-transition-name at a time. This is why dynamic assignment works because you assign the name to the old element, perform the transition, assign it to the new element, then clean up.

Silent failure occurs when duplicate names exist. The browser doesn't throw an error, but the transition doesn't work as expected.

Get your hands into that DOM

Visibility-based approaches using opacity, display: none, or visibility: hidden don't create distinct old and new states. The same element with the same transition name exists before and after, giving the browser nothing to animate between.

True DOM manipulation means:

• Removing the old element completely (element.remove() or container.innerHTML = '', which removes all child elements)
• Creating and inserting a new element (container.appendChild(newElement))
• Allowing the browser to see two distinct elements with the same transition name in different states

If your component architecture requires keeping elements in the DOM (for example, for performance reasons with many panels), consider using view transitions only for the active content area and handling inactive states separately.

When to dynamically name your children

Static view-transition-name assignments in CSS create persistent identifiers that can cause conflicts. Instead, assign transition names programmatically just before transitions.

For elements that participate in transitions:

// Before transition
element.style.setProperty('view-transition-name', 'unique-identifier');

// After transition completes
transition.finished.then(() => {
  element.style.removeProperty('view-transition-name');
});

For elements that always transition (like indicators or badges), static CSS naming is appropriate:

.notification-badge {
  view-transition-name: notification-badge;
}

The distinction is whether the element always exists and always transitions (static naming) or appears and disappears conditionally (dynamic naming).

Component separation extends this principle. When a component has multiple independently animating parts (like tabs with indicators), assign different transition names:

.tab-indicator {
  view-transition-name: tab-indicator;
}

.tab-content {
  /* Assigned dynamically in JavaScript */
}

This allows each part to animate independently without interfering with the other.

A Practical implementation checklist

A systematic approach to view transitions prevents common mistakes and ensures reliable behaviour. Let's break it down so we can learn about what happens before, during, and after transitions.

Before a transition

Identify the departing element. Find the current element that will be replaced. Store a reference to it if you'll need to access it within the transition callback.

const currentElement = container.querySelector('.active-content');

Assign view-transition-name. Give the current element a unique view-transition-name. This must happen before calling startViewTransition(). That is, before the function is invoked, not just before the callback executes.

if (currentElement) {
  currentElement.style.setProperty('view-transition-name', 'content-transition');
}

// The view-transition-name is assigned BEFORE this line executes
const transition = document.startViewTransition(() => {
  // DOM manipulation happens here
});

Verify uniqueness. Ensure no other element on the page currently has this view-transition-name. Use DevTools to check for duplicate names if transitions aren't working.

Check accessibility state. Ensure the current element has appropriate ARIA attributes that will be replicated in the new element (role, aria-labelledby, etc.).

During a transition

Perform minimal DOM operations. Keep the transition callback focused. Fetch data and prepare content before the transition, not within it.

// Good: prepare first
const newContent = await fetchContent();
document.startViewTransition(() => {
  updateDOM(newContent); // Fast operation
});

// Bad: slow operations block transition
document.startViewTransition(async () => {
  const newContent = await fetchContent(); // Blocks!
  updateDOM(newContent);
});

Assign the view-transition-name to the new element. After creating/revealing the new element, assign it the same view-transition-name as the old element.

document.startViewTransition(() => {
  container.innerHTML = '';
  const newElement = createNewElement();
  newElement.style.setProperty('view-transition-name', 'content-transition');
  container.appendChild(newElement);
});

Maintain focus context. If the old element had focus, ensure the new element receives focus after the transition. Use element.focus() at the end of your transition callback.

document.startViewTransition(() => {
  updateDOM();
  newElement.focus(); // Maintain keyboard navigation context
});

After a transition

Clean up view-transition-name values. Remove dynamic view-transition-name values once the animation completes. This prevents naming conflicts in subsequent transitions.

transition.finished.then(() => {
  element.style.removeProperty('view-transition-name');
});

Verify DOM state. Ensure your new state is fully established. Check that event listeners are attached, ARIA attributes are correct, and the component is interactive.

Handle focus restoration. For components that overlay content or temporarily block interaction, ensure focus returns to the appropriate element when they close or hide.

const triggerElement = document.activeElement;

// … later when closing
transition.finished.then(() => {
  triggerElement.focus();
});

Update screen reader context. If the content change is significant and outside the user's current focus, use aria-live to announce it.

transition.finished.then(() => {
  announcer.textContent = `Switched to ${newTabLabel}`;
});

Common and silent errors

View transitions fail silently, which makes debugging frustrating. The browser doesn't throw errors — the animation just… doesn't happen.

Duplicate view-transition-name values. Multiple elements with the same view-transition-name. The broken tabs example demonstrated this issue well for us. All panels existed simultaneously with potential naming conflicts. The solution was to ensure unique names or use dynamic assignment.

Timing issues. Assigning view-transition-name values after the transition starts. The browser captures state at the moment startViewTransition() is called. The solution is to assign names before the function is invoked.

Persistent names. This occurs when view-transition-name values are not cleaned up after use. When transition names remain attached to hidden or inactive elements, they can interfere with subsequent animations. The solution is to remove transition names in the finished callback.

CSS specificity conflicts. Inline styles might be overridden by CSS selectors. The solution is to use setProperty() with inline styles or increase CSS specificity.

Browser support. View transitions aren't supported in all browsers (yet). Always check for support and provide fallbacks and/or lean into progressive enhancement:

function withViewTransition(callback) {
  if ('startViewTransition' in document) {
    return document.startViewTransition(callback);
  } else {
    callback();
    return {
      finished: Promise.resolve(),
      ready: Promise.resolve(),
      updateCallbackDone: Promise.resolve()
    };
  }
}

Memory leaks. Creating elements without removing them or failing to clean up event listeners. Even though JavaScript is good at garbage collection, a good practice is to ensure complete element removal and use AbortController for event listener cleanup.

Wrapping up

So what's the takeaway from all this blinking? The browser needs clear signposts: "this element was here, and now it's here." Miss those signposts, and you get the dreaded blink.

The view transitions blink stems from the browser's inability to correlate elements between old and new states. This happens when view-transition-name assignments are missing, duplicated, or applied at the wrong time.

This debugging experience taught me the core lesson: the browser needs distinct before-and-after states. Everything else is implementation details.

The solution is systematic:

1. Explicitly identify old elements before transitions
2. Perform true DOM manipulation rather than visibility toggles
3. Assign matching view-transition-name values to new elements
4. Clean up names after transitions complete
5. Maintain accessibility throughout the transition lifecycle

These patterns apply broadly across components. Whether building tabs, modals, carousels, or custom interfaces, the principles remain the same: clear element identity, proper DOM manipulation, and careful lifecycle management.

View transitions offer powerful capabilities for creating smooth, professional animations. Understanding element correlation and following these patterns ensures that capability is realised without the frustrating blink.