22 CSS Avatars

Three declarations do the work: border-radius: 50%, aspect-ratio: 1 and object-fit: cover. The last one is the part people skip, and it is what stops a non-square photo from stretching — cover crops the overflow instead of distorting the face. Set the size once with a custom property (--size: 3rem) applied to both inline-size and block-size, or lean on aspect-ratio: 1 and set only the width, which keeps the two from drifting apart when someone edits one and forgets the other. Add object-position: center top when your source photos are portraits, because faces usually sit in the upper third and a centre crop can cut foreheads. Always use a real img element rather than a background image: a background cannot carry alt text, so screen-reader users lose the person's name entirely.

A border participates in layout; a box-shadow does not. Add a 3px border to a 48px avatar and, under the default content-box sizing, the element becomes 54px and every neighbour shifts — which is why avatar rows jump when a ring appears on hover or on an active state. box-shadow: 0 0 0 3px currentColor paints the identical ring with zero layout cost, so rows stay stable and you can animate the spread freely. It also stacks: two shadows give you the gap ring (a page-coloured inner shadow, then the accent outer) that Instagram and Slack both use, which is fiddly with borders. Use outline with outline-offset as a third option, but reserve it for focus states so you do not fight the focus ring. Borders remain the right call when you genuinely want the ring to occupy space, such as a chunky frame that is part of the layout.

Flexbox plus a negative inline margin on every item after the first. Set display: flex on the list, then margin-inline-start: -0.75rem on li + li — a value of roughly a third of the avatar size reads as a deliberate stack rather than a collision. Give each avatar a ring in the page background colour so neighbours separate visually where they overlap; without that ring the faces blur into one shape. Stacking order matters more than people expect: the natural order puts later items on top, which looks wrong because the stack appears to run backwards. Fix it with flex-direction: row-reverse plus reversed margins, or by assigning descending z-index values. For the overflow counter, make the +12 chip the last item with exactly the same dimensions and ring as a real avatar, and expose the full count to assistive tech — aria-label="and 12 more team members" — since a bare plus sign means nothing when read aloud.

It depends entirely on whether the person's name already appears nearby. If the avatar sits alone — a bare facepile, an account-menu trigger — the alt text carries the name: alt="Priya Sharma". If the name is right beside the image as visible text, or already on the link's aria-label, then the image is decorative and alt="" is correct, because otherwise a screen reader announces the name twice in a row. Never write alt="avatar" or alt="profile picture"; that tells a user nothing they could not infer and adds noise. Do not put the status in the alt either — an online dot is separate information and needs its own text equivalent, usually a visually hidden span reading "online", so that presence is not conveyed by a coloured dot alone. This collection follows exactly that split, which is why some demos ship names in alt and others deliberately ship empty alt.

Render the initials as real text in the same box the image would occupy, then let CSS pick the background. The most maintainable version has the server or component set one custom property — style="--hue: 217" — and the CSS builds the fill from it with background: oklch(65% 0.13 var(--hue)). Deriving the hue from a hash of the user's name gives every person a stable colour that survives reloads. Centre the letters with grid, and size them relative to the avatar (font-size: 40%) so initials scale with the container instead of needing a value per size. The trap is contrast: a generated palette will eventually produce a light fill under white text and fail WCAG AA. Working in oklch() helps because lightness is perceptually uniform, so pinning L to a fixed value keeps every hue at a predictable contrast against the same text colour.

Layer the fallback underneath and let the broken image reveal it. Put an initials block in the container, position the img above it, and when the image fails the layer beneath simply shows through — no JavaScript required if you accept the browser's broken-image icon being hidden by the img's own background. For a fully clean result, one line of JS is the pragmatic answer: onerror sets a data attribute or removes the image, and CSS handles the rest. With :has() you can now style the wrapper based on the image state without any script at all in browsers that support it. Whichever route you take, make sure the fallback carries the same accessible name as the image would have, or the user goes from hearing a name to hearing nothing. Demo 15 in this collection deliberately points at a dead URL so you can watch the fallback fire rather than take it on trust.

They can be, and the failure modes are consistent enough to check in a minute. Use a real img with considered alt text, never a background image, so the name reaches assistive tech. Never convey status by colour alone — an online dot needs a shape difference, an icon, or visually hidden text, because a red-green distinction is invisible to a large share of users. Expose counts as numbers: a badge showing 99+ should carry aria-label="127 unread notifications" so the real figure is available. Interactive avatars must be real button or a elements with a visible focus ring and a 44×44px minimum target per WCAG 2.5.8, which often means padding around a smaller visual avatar. Hover-only profile cards are the most common trap in this space: if the card appears on hover it must also appear on keyboard focus, or the content is unreachable without a mouse.

The CSS ports unchanged — every .av-NN selector and custom property is framework-agnostic, and 16 of the 22 designs use no JavaScript at all. The natural component boundary is a single Avatar that accepts size, shape, status and a fallback, with the size scale from demo 21 as its prop contract: one --size property drives the ring, badge and status dot together, so a consumer sets size="lg" and everything scales in proportion. Group components then compose that Avatar rather than restyling it. For Tailwind, the shapes and rings map to rounded-full and ring-2 ring-white directly; the generated-hue trick needs an arbitrary value or a CSS variable set inline, since the palette is per-user data rather than a design token. The six JavaScript demos are small init functions that port to useEffect with a cleanup return, onMounted with onBeforeUnmount, or Svelte's onMount.