The CSS ::checkmark pseudo-element is used to style the checked state of input elements with checkers including the <select> dropdown, checkboxes, and radio buttons. There’s one problem: at the time of writing, ::checkmark lacks browser support on two major browsers: Safari & Firefox.

That’s not all.

According to the specification, ::checkmark is supposed to support styling of checkmarks present in checkboxes, radios, and option elements, but again, at the time of writing, it’s only supported for <option> elements in the <select> dropdown.

This means that ::checkmark , as simple, powerful, and useful as it is, is still very limited, and that’s a problem. So, do we rely on the traditional solutions we used to use in the past to style checkmarks? Are they better? In this article, we will be exploring how the problem of customised checkmarks was solved in the past and compare those solutions with the modern ::checkmark solution, providing recommendations as we go.

How we’ve traditionally approached checkmarks in menus

To create and style a traditional checkmark similar to the ones you see in <option> elements under <select> , first, we would create a custom dropdown to house the checkmark. To do that, we would have to consider a bunch of interactive states and rules. Your browser doesn’t provide these with non-semantic elements, so taking a few notes from Sandrina’s article, we need to have:

• A dropdown with the current selected option
• Box toggling ability to toggle the visibility of the options
• Clicking an option in the list updates the dropdown value. The dropdown text changes, and the list MUST be closed
• Clicking outside closes the list
• A customizable select dropdown icon to represent our picker
• A customizable select checkmark icon to represent our checkmark for any selected option

Here’s how our HTML would likely look:

<div id="cs">
    <div id="cs-btn">
      <span id="btn-lbl">::before</span>
      <span class="btn-arrow">▼</span>
    </div>
    
    /* list menu */
    <div class="cs-menu">
      <div class="item" data-sel data-v=":before">
        <span class="checkmark">✓</span>
        <span class="label">::before</span>
          
        </div>
      <div class="item" data-v="::after">
        <span class="checkmark">✓</span>
        <span class="label">::after</span> 
        </div>
      <div class="item" data-v="::marker">
        <span class="checkmark">✓</span>
        <span class="label">::marker</span>  
        </div>
      <div class="item" data-v="::selection">
        <span class="checkmark">✓</span>
        <span class="label">::selection</span>
        </div>
        
      <div class="item" data-v="::placeholder">
        <span class="checkmark">✓</span>
        <span class="label">::placeholder</span>
        </div>
    </div>
  </div>

And our main CSS for the dropdown would look something like this:

/* position property sets the list dropdown menu to be centered and non-clickable, just below the button that reveals it*/
.cs-menu {
  position: absolute;
  top: calc(100% + 0.4rem);
  left: 0;
  right: 0;
  background: var(--surface);
  border: 1px solid var(--border);
  border-radius: 0.5rem;
  padding: 0.3rem;
  z-index: 20;
  box-shadow: 0 1.5rem 3rem oklch(0% 0 0 / 0.55);
  opacity: 0;
  transform: translateY(-0.4rem);
  pointer-events: none;
  transition: opacity 0.15s, transform 0.15s;
}

/* this reveals the menu list when the dropdown menu button is clicked if data-open attribute is present. It is hidden otherwise */ 
#cs[data-open] .cs-menu {
  opacity: 1;
  transform: translateY(0);
  pointer-events: all;
}

/* you can use flex here instead of grid. Just follow the pattern stated */
.item {
  display: grid;
  grid-template-columns: 1.2rem 1fr;
  align-items: center;
  gap: 0.65rem;
  padding: 0.6rem 0.75rem;
  border-radius: 0.4rem;
  cursor: pointer;
  transition: background 0.1s;
}
.item:hover {
  background: var(--hover);
}
.item[data-sel] {
  background: oklch(75% 0.18 55 / 0.08);
}

.label {
  font-size: 0.88rem;
  color: var(--muted);
  transition: color 0.12s;
}
.item[data-sel] .label {
  color: var(--accent);
}

/* checkmark over here 🙋‍♂️ */
.checkmark {
  justify-self: end;
  font-size: 0.75rem;
  font-weight: 700;
  color: var(--accent);
  visibility: hidden;
}
.item[data-sel] .checkmark {
  visibility: visible;
}

In essence, we’re using position absolute to remove the element from the normal document flow and hide it from the user. revealing the menu only when the dropdown is clicked. Then, we’re using grid to align and arrange the items in the dropdown menu.

Finally, we style the checkmark to be hidden by default on all list items, and only the selected item should reveal the checkmark, indicating it has been chosen!

Ah yes! That should be all, right?

All this code should make sure the dropdown and checkmark work as intended, fulfilling the requirements stated above. Surely, it works without JavaScript (JS). But, enough sarcastic talk, let’s see the result…

See the Pen The dilemma of custom select dropdown with checkmarks: no js, a problem by Andy Bell (@piccalilli) on CodePen.

Notice something not working? Yes, the dropdown is not working. Why? It’s because there’s no JS to provide the interactivity!

That’s a big issue with solutions like this because JS is required for them to work, and JS will fail for your users. Warnings about best practice aside, let’s provide some interactivity to at least get this sample working.

const cs = document.getElementById("cs");
const btn = document.getElementById("cs-btn");
const lbl = document.getElementById("btn-lbl");
const items = document.querySelectorAll(".item");

btn.addEventListener("click", () => cs.toggleAttribute("data-open"));

items.forEach((item) =>
  item.addEventListener("click", () => {
    items.forEach((x) => x.removeAttribute("data-sel"));
    item.setAttribute("data-sel", "");
    lbl.textContent = item.dataset.v;
    cs.removeAttribute("data-open");
  })
);

document.addEventListener("click", (e) => {
  if (!cs.contains(e.target)) cs.removeAttribute("data-open");
});

See the Pen Custom dropdown using grid/flex with position property by Andy Bell (@piccalilli) on CodePen.

We are missing two important points. What about accessibility and users who want to navigate via keyboard?

We will have to modify the HTML with some aria-haspopup , aria-expanded, aria-selected, role, tab-index, and aria-label . That would sort out our HTML accessibility dilemma. The code would look a lot like this. Setting it up this way from the start, although tedious, would ensure checkmarks in our dropdowns work as intended for all users:

	<div id="cs">
		<!-- Button to open/close dropdown -->
      <button id="cs-btn" aria-haspopup="listbox" aria-expanded="false">
        <span id="btn-lbl">::before</span>
        <span class="btn-arrow">▼</span>
      </button>
      
      <!-- Menu itself -->
      <div class="cs-menu" 
	      id="cs-menu" 
	      role="listbox" 
	      aria-label="CSS pseudo-element"
      >
        <div class="item" 
	        role="option" 
	        data-sel 
	        aria-selected="true" 
	        data-v=":before"
	        tabindex="-1"
	        >
          <span class="checkmark">✓</span>
          <span class="label">::before</span>
        </div>
        
        <div class="item" 
	        role="option" 
	        aria-selected="false" 
	        data-v="::after"
	        tabindex="-1"
	        >
          <span class="checkmark">✓</span>
          <span class="label">::after</span>
        </div>
        
        <div class="item" 
	        role="option" 
		      aria-selected="false" 
		      data-v="::marker"
		      tabindex="-1"
		      >
          <span class="checkmark">✓</span>
          <span class="label">::marker</span>
        </div>
        
        <div class="item" 
	        role="option" 
	        aria-selected="false" 
	        data-v="::selection"
	        tabindex="-1"
	        >
          <span class="checkmark">✓</span>
          <span class="label">::selection</span>
        </div>
        
        <div class="item" 
	        role="option" 
	        aria-selected="false" 
	        data-v="::placeholder"
	        tabindex="-1"
	        >
          <span class="checkmark">✓</span>
          <span class="label">::placeholder</span>
        </div>
      </div>
    </div>
  </div>

Then, for our JavaScript, that will be modified a bit from what you saw earlier. We would have to account for when the user uses the directional arrows up and down, and when they click enter and esc to navigate the dropdown and click on any option.

const cs = document.getElementById("cs");
const btn = document.getElementById("cs-btn");
const lbl = document.getElementById("btn-lbl");
const items = [...document.querySelectorAll(".item")];

let selected = items.find((i) => i.hasAttribute("data-sel"));

function open() {
  cs.setAttribute("data-open", "");
  btn.setAttribute("aria-expanded", "true");
  (selected ?? items[0]).focus();
}

function close() {
  cs.removeAttribute("data-open");
  btn.setAttribute("aria-expanded", "false");
  btn.focus();
}

function select(item) {
  selected?.removeAttribute("data-sel");
  selected?.setAttribute("aria-selected", "false");
  item.setAttribute("data-sel", "");
  item.setAttribute("aria-selected", "true");
  selected = item;
  lbl.textContent = item.dataset.v;
}

btn.addEventListener("click", () =>
  cs.hasAttribute("data-open") ? close() : open()
);

btn.addEventListener("keydown", (e) => {
  if (e.key === "ArrowDown") {
    e.preventDefault();
    open();
  }
});

/* accounting for keyboard up, down, enter and esc for the dropdown */
items.forEach((item) => {
  item.addEventListener("click", () => {
    select(item);
    close();
  });
  item.addEventListener("keydown", (e) => {
    const i = items.indexOf(item);
    if (e.key === "ArrowDown") {
      e.preventDefault();
      items[(i + 1) % items.length].focus();
    }
    if (e.key === "ArrowUp") {
      e.preventDefault();
      items[(i - 1 + items.length) % items.length].focus();
    }
    if (e.key === "Enter" || e.key === " ") {
      e.preventDefault();
      select(item);
      close();
    }
    if (e.key === "Escape") close();
  });
});

document.addEventListener("click", (e) => {
  if (!cs.contains(e.target)) close();
});

That’s a lot of JavaScript! And essentially, what I’m doing is accounting for when a user clicks the down arrow button on their keyboard, which can be used to expand the dropdown and also browse downwards through the options. The up arrow key inside the dropdown can be used to navigate up, enter selects the item, and esc leaves the dropdown.

See the Pen custom dropdown using grid/flex with position property by Andy Bell (@piccalilli) on CodePen.

Let’s also not forget the accessibility toggles that let the screen reader know that the dropdown has been expanded or that an item in the dropdown list has been selected.

This approach is how many developers have tackled the problem at hand before and here two key reasons why it is not the best solution:

1. When JS fails, the whole solution is dead. Not even a glimmer of hope is here. No JavaScript means no interaction and the markup we added likely ends up creating even more problems for people using assistive technology
2. Every single browser behavior has to be unnecessarily implemented from scratch. From option focusing, to accounting for what happens when the user clicks the button to expand and close the dropdown and also clicks outside of the dropdown to close it, has to be implemented

In essence, this solution is fragile and unreliable due to its over-reliance on JS. What’s more? Our checkmark styles are nonexistent if the dropdown cannot be revealed!

So, how do we solve these issues? Luckily, there’s a far less “heavy code” intensive solution that allows us to do style checkmarks anyhow we like.

Modern day ::checkmark styling

The CSS ::checkmark is a pseudo-element that allows us to apply styles to HTML elements that support a checkmark. It really helps remove the hassle of writing a bunch of HTML, CSS, and JS in order to make things work as they’re supposed to. Let’s take a custom dropdown and a checkmark designed using ::checkmark.

Take for example, this <select>dropdown:

<select id="ls">
	<option value="css">CSS</option>
	<option value="js">JavaScript</option>
	<option value="html">HTML</option>
  <option value="ts">TypeScript</option>
  <option value="rust">Rust</option>
</select>

The HTML is pretty concise when compared to the previous solution, right? It’s amazing what happens when we use semantic elements. This way, the browser handles everything for us. Accessibility, keyboard navigation, and every standard behavior we expect from our dropdown, without any hassle. Just define a dropdown using <select> with its <option>s and boom! We’re good to go.

Checkmarks even come out of the box with this native browser solution!

For our CSS, we would have something like this:

/* required to make the checkmark stylable */ 
#ls,
::picker(select) {
  appearance: base-select;
}

#ls {
  background: var(--surface);
  border: 1px solid var(--border);
  border-radius: 0.6rem;
  padding: 0.7rem 1rem;
}

#ls option:checked {
  color: var(--accent);
  background: oklch(78% 0.22 145 / 0.1);
}

/* checkmark style here 🙋‍♂️*/
::checkmark {
  content: "🎨";
}

/* a dot checkmark for options not checked */
#ls option:not(:checked)::checkmark {
  visibility: visible;
  content: "·";
  color: var(--muted);
}

All you need to do is set appearance to base-select on the <select> dropdown and you’re set for styling your checkmarks using ::checkmark and changing the default check using content!

See the Pen ::checkmark demo (no JS required!) by Andy Bell (@piccalilli) on CodePen.

No JS required!

A win for progressive enhancement because it essentially accounts for all the major issues associated with creating a custom dropdown and having a custom checkmark style. This solution, even when JS fails, will still work out fine.

This approach is clearly better than the previous approach, but there are a few issues with this that I think we should touch on.

The problem with ::checkmark

It’s amazing what this pseudo-element can do and what it is intended to do. It’s also amazing the amount of code it saves. Not only do I need to write less code to achieve the same result (efficiency), but the browser also handles the default behavior I expect when I click outside the dropdown (the dropdown closes automatically).

There are a few issues with ::checkmark that I want to address though.

1. There’s limited browser support. At the time of writing, ::checkmark is only supported in 3 major browsers and not across the board. That would suck for a user having to experience a feature in one browser and be absent on the next.
2. Lacking full feature support: According to the documentation, ::checkmark is supposed to work for checkboxes, radios, and options. Guess what? In browsers that currently support this, only the options from <select> are supported. So even if I’m using this pseudo-element, I’m not getting its full feature!

Both need to be looked into by browser vendors, in my opinion.

Wrapping up

The modern day ::checkmark solution with native browser dropdown allows us to favor all users without having to implement our own accessibility, keyboard navigation, and dropdown behavior. Even when JavaScript fails, the solution still works! Because we're using a native <select> element, we get the correct announcements from assistive technology too.

My only plea is that for our checkmarks to be styled correctly, major browser vendors may need to provide full support for this feature as soon as possible, so we can style our own custom checkmarks without having to rely on JS at all, ever again.

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.