feat(avatar-stack): new component #4331

oddvernes · 2025-12-16T15:20:16Z

resolves #2306

changeset-bot · 2025-12-16T15:20:20Z

🦋 Changeset detected

Latest commit: 2e8db38

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 5 packages

Name	Type
@digdir/designsystemet-react	Minor
@digdir/designsystemet-css	Minor
@digdir/designsystemet	Minor
@digdir/designsystemet-theme	Minor
@digdir/designsystemet-types	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions · 2025-12-16T15:24:00Z

Preview deployments for this pull request:

storybook - 8. Jan 2026 - 12:21

oddvernes · 2026-01-06T12:11:10Z

Needs feedback/approval before creating documentation on www

packages/css/src/avatar-stack.css

eirikbacker · 2026-01-06T14:51:28Z

packages/css/src/avatar-stack.css

+}
+
+.ds-avatar-stack {
+  /*The following variables can be defined in a parent of .ds-avatar-stack:


out of curiosity, why do we want these variables to potentially be defined in the parent? And if so, should we now start the work of making this possible for all components? 🤔

This is how i would have implemented the public variables so they can be inherited instead of having to override the class.

--gap: var(--dsc-avatar-stack-gap, 2);

a short-named local variable pointing to the undefined full-named variable --dsc-avatar-stack-gap or otherwise use the fallback

I see ☺️ but this is not how any other components are implemented yet, so, I think we should either stick to the existing convention, as varying code conventions is raising the bar for how easy it is to be an outside contributor to this project. Or, we should convert all components to follow the convention, and write about it in https://github.com/digdir/designsystemet/wiki/Coding-conventions ☺️

I think we should stick to our convention here. Our consumers expect our variables to be prefixed with --ds- or --dsc-, and having variables such as --gap goes against this, and opens up for unwanted behaviour

The --dsc- variables are there just as in every component, the only difference being they can be defined on root or in a parent and inherited down for a marginal extra convenience. But i'll remove this feature for now 👍

yes, very much want this convenience <3 but let's do it will all components at once so we find and test edge cases and potential solutions at the same time ☺️

eirikbacker · 2026-01-06T14:56:24Z

packages/react/src/components/avatar-stack/avatar-stack.tsx

+      gap,
+      avatarSize,
+      overlap,
+      max = 4,


I'm unsure if max should be part of the component, or if we should rather have:

<AvatarStack> <Avatar /> <Avatar /> +2 </AvatarStack>

This would make the CSS and component less complex, and closer to the pure HTML/CSS edition? ☺️

Perhaps.. Since we cant use sibling-count() yet there is javascript required for this logic regardless. 🤷

mm, but, why would we need sibling-count? I'm, thinking it is the consumers responsibility to add the correct amount of Avatar-components in the element? ☺️ We can huddle if you want :)

I agree, it's fine to make the consumer add the "remaining" number themselves.
A data attr should be fine here, if that's easier for the CSS to work.

(logic involving sibling-count could possibly be used to automatically display: none the beyond maximum avatars i think.. but it is not relevant for a while anyway)

I can delete the react logic but keep the data-additionals selector perhaps, for easier styling, instead of putting text-fragment as a child?

Sound good to me :)

☺️ sounds good! I think a text fragemnt is nice because it can be styled otherwise and add HTML-elements etc ☺️ but I see both pros/cons. I do not think we should need or do any display:none logic - what is in the HTML is what the user sees 🤝 😇

I added align-items: center so now you can choose to use data-suffix for pre-styled text or add whatever you want as a last child inside AvatarStack. Unfortunately adding something as first-child works less well because there is no :nth-first-child(1 of .ds-avatar) as there is :nth-last-child(1 of .ds-avatar), only :first-child (needed to exclude negative margin in the first avatar)

Does :first-child:is(.ds-avatar) work?

I see, hm, how about .ds-avatar:first-child for the first, and .ds-avatar:not(:has(+ .ds-avatar)) for the last? ☺️

eirikbacker · 2026-01-07T20:29:39Z

packages/css/src/avatar-stack.css

+
+.ds-avatar-stack {
+  --dsc-avatar-stack-size: var(--ds-size-12);
+  --dsc-avatar-stack-gap: 2;


Suggestion: can we specify unit here?

Suggested change

--dsc-avatar-stack-gap: 2;

--dsc-avatar-stack-gap: 2px;

as this gives more flexibility? ☺️

Do you feel like the react prop should then specify unit as well or keep that as number converted to px?

eirikbacker · 2026-01-07T20:30:59Z

packages/css/src/avatar-stack.css

+.ds-avatar-stack {
+  --dsc-avatar-stack-size: var(--ds-size-12);
+  --dsc-avatar-stack-gap: 2;
+  --dsc-avatar-stack-overlap: 50;


Suggestion: can we specify unit here too?

Suggested change

--dsc-avatar-stack-overlap: 50;

--dsc-avatar-stack-overlap: 50px;

It seems like this would not be problematic, as the rest of the equations are +/- ☺️

This needs to be a unitless number. it is used in a calculation to create the overlap as a percentage of the avatar size automatically

eirikbacker · 2026-01-07T20:31:35Z

packages/css/src/avatar-stack.css

+  --_gap: calc(var(--dsc-avatar-stack-gap) * 1px);
+  --_overlap: calc(((var(--dsc-avatar-stack-size) / 100) * var(--dsc-avatar-stack-overlap)) * -1);
+
+  --captured-length: var(--_overlap);


could we skip this, a just use --_overlap directly in the rest of the file? ☺️

The registered property is needed to be able to animate the optional expand action. We could rename that to --_overlap or something else instead, but since they have to be declared in global scope, I am in favour of generically named reusable registered custom properties

eirikbacker · 2026-01-07T20:31:54Z

packages/css/src/avatar-stack.css

+  .ds-avatar {
+    --dsc-avatar-size: var(--dsc-avatar-stack-size);
+    --_font-size: max(0.75rem, calc(var(--dsc-avatar-stack-size) * 0.5));
+    mask: radial-gradient(50% 50% at calc(150% + var(--captured-length)), transparent calc(100% - 1px + var(--_gap)), #000 calc(100% + var(--_gap)));


very clever <3

I don't know who came up with this technique first, but it was not me!

eirikbacker · 2026-01-07T20:33:54Z

packages/css/src/avatar-stack.css

+      font-size: var(--_font-size);
+    }
+    > a {
+      line-height: 0;


I do not understand these child selectors (&[data-initials]:empty::before, > span and > a) intuitively - why are they needed? Why are they not in .ds-avatar? I assume there is good reasons, so a comment would be super ☺️

eirikbacker · 2026-01-07T20:35:13Z

packages/css/src/avatar-stack.css

+    &:not(:first-child) {
+      margin-left: var(--captured-length);
+    }
+    &:nth-last-child(1 of .ds-avatar) {


Could this instead be .ds-avatar:not(:has(+ .ds-avatar)) for even better browser support? ☺️

looks like :has came out a year earlier than :nth-last-child(1 of ...) for chrome (2022 vs 2023), while :has came after nth-last-child in the other browsers. I can add @supports blocks and use both i suppose
https://caniuse.com/css-nth-child-of
https://caniuse.com/css-has

eirikbacker · 2026-01-08T08:05:44Z

packages/react/src/components/avatar-stack/avatar-stack.stories.tsx

+    >
+      <legend>Link expandable</legend>
+      <AvatarStack {...args} expandable='fixed'>
+        <Avatar aria-label=''>


Can we use asChild on avatar, so we avoid extra nesting? ☺️

Suggested change

<Avatar aria-label=''>

<Avatar aria-label='' asChild>

are you thinking asChild="a" use case? It would be a new feature added to Avatar

wip avatar-stack

036bdf1

Merge branch 'main' into feat/avatar-stack

c50f815

oddvernes added 22 commits December 16, 2025 16:28

hook up vars

caa11af

make overlap input a percentage

bbfd917

more wip

cc394ce

Merge branch 'main' into feat/avatar-stack

dd5892f

more wip, support square

782e1de

test tooltip

a029c0d

make it work with link inside avatar

766df76

overlap story

0b67e5a

refactor/rename variables

ca47a5e

Merge branch 'main' into feat/avatar-stack

fe47b74

fixed width expand optional

0df3702

Merge branch 'main' into feat/avatar-stack

ea6a70e

focusable if expandable

8e878a4

changesets

85bbc35

remove defaults from react

7f3a7ac

handle gap 0

cff237a

interactive story for size/gap/overlap

61ca64c

add more to playground story

d0a97b3

remove a fieldset

d37bbd9

Merge branch 'main' into feat/avatar-stack

a9534d0

default gap 2px

9e17550

Merge branch 'main' into feat/avatar-stack

868d606

oddvernes marked this pull request as ready for review January 6, 2026 12:10

oddvernes requested review from Barsnes, eirikbacker and mimarz as code owners January 6, 2026 12:10

Barsnes reviewed Jan 6, 2026

View reviewed changes

packages/css/src/avatar-stack.css Outdated Show resolved Hide resolved

oddvernes added 2 commits January 6, 2026 15:45

fix overlap 0 = falsy

f50448e

Merge branch 'main' into feat/avatar-stack

3f55678

eirikbacker reviewed Jan 6, 2026

View reviewed changes

oddvernes added 3 commits January 7, 2026 12:25

Merge branch 'main' into feat/avatar-stack

0818a70

biome

9b5546b

remove logic and rename variables

f5affc2

eirikbacker reviewed Jan 7, 2026

View reviewed changes

align center default

b718ad6

eirikbacker reviewed Jan 8, 2026

View reviewed changes

Merge branch 'main' into feat/avatar-stack

2e8db38

	--dsc-avatar-stack-overlap: 50;
	--dsc-avatar-stack-overlap: 50px;

feat(avatar-stack): new component #4331

Are you sure you want to change the base?

feat(avatar-stack): new component #4331

Conversation

oddvernes commented Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions bot commented Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oddvernes commented Jan 6, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oddvernes Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oddvernes Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oddvernes Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oddvernes Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eirikbacker Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oddvernes Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

oddvernes commented Dec 16, 2025 •

edited

Loading

changeset-bot bot commented Dec 16, 2025 •

edited

Loading

github-actions bot commented Dec 16, 2025 •

edited

Loading

oddvernes Jan 6, 2026 •

edited

Loading

oddvernes Jan 7, 2026 •

edited

Loading

oddvernes Jan 8, 2026 •

edited

Loading

oddvernes Jan 8, 2026 •

edited

Loading

eirikbacker Jan 7, 2026 •

edited

Loading

oddvernes Jan 8, 2026 •

edited

Loading