Building an overlapping avatar row

A row of round images that overlap slightly is a familiar design pattern, so the interesting work here is not the overlap itself but making it responsive. The goal is to compute the overlap dynamically so that all images always fit inside their container, with transparent gaps between them and a hover animation on top. The demo for this technique is currently limited to Chrome and Edge; it should work elsewhere once sibling-index() and sibling-count() land more broadly. Firefox progress is tracked in Ticket #1953973 and WebKit's position in Issue #471. A second article will go further into circular lists.

Starting layout

The markup is a parent container holding a set of img elements:

<div class="container">
  <img src="" alt="">
  <img src="" alt="">
  <img src="" alt="">
  <img src="" alt="">
  <!-- etc. -->
</div>

Flexbox on the container puts them in one row:

.container {
  display: flex;
}

Circles come from border-radius, and the overlap comes from a negative margin. The initial value is arbitrary:

.container img {
  border-radius: 50%;
  margin-right: -20px;
}
.container img:last-child {
  margin: 0;
}

Cutting a transparent gap with mask

Keeping the gap transparent takes more care than it looks, because each cut-out has to account for the neighbouring element so one image never simply hides another.

mask: radial-gradient(50% 50% at calc(150% - 20px), #0000 100%, #000);

The mask draws a circle with the image's own dimensions (a 50% radius in both directions) centred on the midpoint of the next element at calc(150% - 20px). Without overlap, that centre would sit at 50% + 100%; the 20px subtraction matches the margin and pulls the circle closer, cutting into the right side. Moving the circle the other way — 50% - 100% + 20px — cuts the left side instead. Applying this across all images gives the effect, with a few CSS variables controlling image size and gap:

.container {
  --s: 120px; /* image size*/
  --g: 10px;  /* the gap */

  display: flex;
}
.container img {
  width: var(--s);
  border-radius: 50%;
  margin-right: -20px;
  /* Cut-out on the right side */
  mask: radial-gradient(50% 50% at calc(150% - 20px),
        #0000 calc(100% + var(--g)),#000);
}
/* Cut-out on the left side */
.container.reverse img {
  mask: radial-gradient(50% 50% at calc(-50% + 20px),
        #0000 calc(100% + var(--g)),#000);
}
.container img:last-child {
  margin: 0;
}
.container.reverse img:first-child,
.container:not(.reverse) img:last-child {
  mask: none;
}

The .reverse class flips the cut-out from right (the default) to left. This works, but it is static; the natural next improvement is to enlarge the overlap on small screens to save space, or remove it on wide screens where there is room for full images.

Deriving a responsive overlap

When the total image width exceeds the container, the negative margin must absorb the excess. The naive route is JavaScript plus a resize listener, but the margin can be expressed directly in CSS:

margin-right: (size_of_container - N x size_of_image)/(N - 1);

N is the number of images and the divisor is N - 1 because the last image needs no margin. The image size is already in --s, and the container width is 100%:

margin-right: (100% - N x var(--s))/(N - 1);

Solving for N is where sibling-count() helps: it returns the number of child elements automatically, so ten images yield a value of 10 without any hard-coded magic number in the CSS.

margin-right: calc((100% - sibling-count() * var(--s))/(sibling-count() - 1));

One refinement: on a container wide enough, the computed margin turns positive and the images spread apart. The formula can be capped using min(), which sets a maximum (just as max() sets a minimum):

margin-right: min((100% - sibling-count() * var(--s))/(sibling-count() - 1), 0px);

Reusing the gap variable --g keeps a little spacing between items:

margin-right: min((100% - sibling-count() * var(--s))/(sibling-count() - 1), var(--g));

Now the same value needs to feed the mask as well.

Two images on separate rows on opposite ends of each row. The top row image is aligned right and the bottom row image is aligned left.

Feeding the new formula into the mask makes the images vanish, and the cause is percentages. A percentage margin resolves against the container, while inside mask percentages resolve against a different reference, so the two values are no longer equal. Container query units solve this. First, register the container:

.container {
  container-type: inline-size;
}

Then express the container width as 100cqi (or 100cqw) rather than 100%. Position and mask then stay in sync as the container resizes.

Hover animation and the overflow it causes

Hovering an image should reveal it fully, so the overlap variable is set to zero on :hover:

.container img:hover {
  --_m: 0px;
}

That removes both the margin and the cut-out, so a small gap is preferable. Setting --_m to --g keeps a sliver of space:

.container img:hover {
  --_m: var(--g);
}

Two problems remain: the cut-out looks slightly wrong on the reversed row, and pushing neighbouring images apart overflows one image past the container.

The mask issue comes from using margin-right for spacing when the cut-out is on the left. Matching sides fixes it — margin-right for a right cut-out, margin-left for a left one:

.container:not(.reverse) img {
  mask: radial-gradient(50% 50% at calc(150% + var(--_m)),
        #0000 calc(100% + var(--g)), #000);
  margin-right: var(--_m);
}
.container.reverse img {
  mask: radial-gradient(50% 50% at calc(-50% - var(--_m)),
        #0000 calc(100% + var(--g)), #000);
  margin-left: var(--_m);
}
.container:not(.reverse) img:last-child,
.container.reverse img:first-child {
  mask: none;
  margin: 0;
}

The overflow arithmetic needs adjustment too. Earlier the excess was divided across N - 1 elements; with a hovered image excluded, N becomes N - 1 and N - 1 becomes N - 2:

(size_of_container - (N - 1) x size_of_image)/(N - 2)

The excluded element still occupies space, so its size must come off the container width — its size plus a gap, since a hovered image carries a margin equal to the gap:

((size_of_container - (size_of_image + gap)) - (N - 1) x size_of_image)/(N - 2)

Simplified:

(size_of_container - gap -  N x size_of_image)/(N - 2)

The rule applies to every image except the hovered one, which calls for :has() and :not() in one selector:

/* Select images that are not hovered when the container contains a hovered image */
.container:has(:hover) img:not(:hover) {
  /**/
}
.container:has(:hover) img:not(:hover) {
  --_m: min((100cqw - var(--g) - sibling-count()*var(--s))/(sibling-count() - 2), var(--g));
}

That eliminates overflow on hover in both directions. The remaining step is animating the spacing instead of snapping it, with a transition on --_m:

transition: --_m .3s linear;

As written, the transition will not run, because CSS does not treat the computed value as a length unit. Registering the property with @property fixes that:

@property --_m {
  syntax: "<length>";
  inherits: true;
  initial-value: 0px
}

One edge case is left. The last image of the top list and the first of the bottom list carry no margin and are always fully visible, so hovering them should do nothing. Restricting the selector by :last-child and :first-child handles it:

.container:not(.reverse):has(:not(:last-child):hover) img:not(:hover),
.container.reverse:has(:not(:first-child):hover) img:not(:hover) {
  --_m: min((100cqw - var(--g) - sibling-count()*var(--s))/(sibling-count() - 2),var(--g));
}

The second part of this series extends the pattern to circular lists.