[css-values] Proposal: add sibling-count() and sibling-index()

[argyleink]

Problem

Currently we can query a child based on it's child index position or query on children length (with some complex syntax), but we can't use the index or length as values in our styles. Feels like they're known, but not accessible.

so we end up doing stuff like this:

.el {
  --delay: calc(var(--i, 1) * 400ms);
  animation: fadeIn 1000ms var(--delay) forwards;
  width: 100px;
  height: 100px;
  background: darkorchid;
  margin: 20px;
  opacity: 0;
}

.el:nth-child(2) {
  --i: 2;
}

.el:nth-child(3) {
  --i: 3;
}

@keyframes fadeIn {
  100% { opacity: 1; }
}

above source from Codepen

Proposal

2 new functions: sibling-count() and sibling-index(). These should report values based on element count, not node count.

sibling-count()

This function returns the total length of sibling elements as a number, similar to node.childElementCount (docs) or node.children.length but accessible from a sibling. Consider this like a child asking "how many siblings they have".

example usage

Dynamic background color that changes based on total children in the list

ul > li {
  background-color: hsl(sibling-count() 50% 50%);
}

sibling-index()

This function returns the contextual child index as a number. Similar to the value queried with nth-child, this would be a get() call for the contextual child's index in the tree. Consider this like a child asking "what position am I in this family".

example usage

Dynamic background color that changes based on child index position, resulting in a stepped gradient effect

ul > li {
  background-color: hsl(calc(sibling-index() * 10) 50% 50%);
}

All Together

Example code is a slightly modified version of Jake Archibald's comment here 👍

ul > li {
  /* Stagger from start to end */
  animation-delay: calc(sibling-index() * 100ms);

  /* Stagger from end to start */
  animation-delay: calc(sibling-count() - sibling-index() * 100ms);
}

Use Cases

• staggered animations: example1 example2
• dynamic & contextual color systems
• dynamic & contextual spacing
• dynamic & contextual distance
• etc

Conclusion

Most other proposals for similar functionality, request access to counters() as a unit that can be passed to calc(). But I feel that is overloading the counters feature and is rooted in a mindset of leveraging something "close" to what is needed, where what's actually wanted is the child index position for visually reasonable and meaningful UI feedback and presentation.

By proposing a solution that doesn't involve counters, I hope to bypass much of the pain points associated with the feature to help unblock the large and ever-growing set of use cases that could leverage these contextual values.

Sources & Chatter

#1869
#1176
#1026
https://www.w3.org/TR/selectors-4/#child-index
https://twitter.com/shshaw/status/1201978228375724032?s=20
https://twitter.com/smfr/status/1202276694230306816?s=20 @smfr

[shshaw]

Definitely on board for this. These functions would pave the way for making Splitting.js obsolete and enable some really great animations and effects.

Small point for discussion: Should sibling-count() be the count of all the parent's children OR the count of this element's siblings (practically parent.children.length - 1)? Because "semantically" if you're asking for the count of siblings, it would not include the element itself. In plain language: "I have one brother" versus "My parents have two sons"

[jakearchibald]

Proposal looks good, although it'd be nice if an element could know it's children count too.

[jakearchibald]

I'm not sure why we have two issues though. Feels like one of them should be closed.

[smfr]

Maybe there should also be a depth query (with some consideration for what happens in shadow trees).

[AmeliaBR]

This looks like a straight duplicate of #1869, can we close this & copy the discussion over there?

That conversation discusses the counter-value() as one possible solution, but isn't restricted to it.

[argyleink]

Tab and I felt a new one was due since there were a few issues that alluded to similar functionality but generally had counters() involved or weren't as minimal / specific as this. That's why the issues are linked that helped lead to this one. BUT, I'm ok moving it over to another thread if we want!

[emilio]

Why a function?

(With an implementor hat on) it's a bit unfortunate having to do the element instead of node count, as the first is O(N) but the second is O(1)..

[argyleink]

What could we use that's not a function @emilio!?

Element vs Node, browser internals don't do any distinguishing that you can piggyback on? 0(N), even if the children are fixed and there's no recursion required? tell me more, this sounds interesting 🙂

[emilio]

Well, I was thinking there's nothing really preventing you from using an ident or such (functions without arguments are not great), but I guess that would make some properties that can take <ident> and <number> or <integer> ambiguous. Also I guess I could see sibling-count(<selector>) or something being a thing...

Element vs Node, browser internals don't do any distinguishing that you can piggyback on? 0(N), even if the children are fixed and there's no recursion required? tell me more, this sounds interesting slightly_smiling_face

At least Gecko keeps the node children count in the parent node (here), so getting the sibling node count is just parentNode.childCount - 1 which is pretty fast. For elements, we'd have to actually traverse all children and check they're elements.

There's nothing preventing us from tracking element count either, but it grows every node (or at least container node) which is not great.

But it seems other engines don't do the same optimization as Gecko, so feel free to take that point as an implementation detail...

[Crissov]

This feels like it should be solved either with predefined counters or with predefined variables that do not have a double-hyphen prefix.

• var(n) or var(child) or var(child-n) for the index value used for :nth-child(), which is calc(var(preceding-siblings) + 1), i. e. 1 for :first-child and for :only-child, where var(siblings) = 0
• var(m) or var(last-child) or var(-child) or var(child-m) for the index value used for :nth-last-child(), which is calc(var(succeeding-siblings) + 1) or calc(var(siblings) - var(child) + 2), i. e. 1 for :last-child and for :only-child, where var(siblings) = 0 and var(child) = 1
• var(i) or var(type) or var(type-n) for the index value used for :nth-of-type()
• var(j) or var(last-type) or var(-type) or var(type-m) for the index value used for :nth-last-of-type()

https://drafts.csswg.org/selectors-4/#child-index

[faceless2]

I'd been trying to work up a coherent way to do this using counter() and target-counter() for some time, but I've (somewhat grudgingly) come to the conclusion that a new function is a better option - it avoids all sorts of hazards inherent in counters, which are considerably more complex then they first appear (when it comes to scoping).

I would personally lean towards a new function over a syntax that was a) not a function or b) used var(), because it leaves more room for expansion in the future: it's easy enough to define the sibling-index() function now, with no arguments, and get that implemented. If users demand more in the future, you can supply arguments (e.g. a selector as mentioned by @emilio). You would struggle to defined that cleanly with a var().

Can I suggest that instead of sibling-index() and sibling-count() we consider index(sibling) and count(sibling) - because you can guarantee there will be situations where you want the count of your children rather than siblings, for example to solve the issue from #4211:

ol[reversed] {
    counter-reset: list-item count(children);
}

It would be good to leave that option available in the syntax, even if it's not implemented yet.

(edit: see also #4181)

Idle musing on other uses:

.clockhand {
    position: absolute;
    left: calc(50% + sin(index(sibling) / count(sibling)) * var(--radius));
    top: calc(50% + cos(index(sibling) / count(sibling)) * var(--radius));
}

[jakearchibald]

In #1869 (comment) I showed that if you can get a children count, you can use that to get a sibling count, so if we need an minimum viable product, then I'd rather have a children count than sibling count.

I also think "sibling count" is misleading. For example, I am one of two children, but doesn't that mean I have one sibling? Whereas here we're using "sibling count" to mean "sibling count + myself".

[faceless2]

How about index(element) and/or index(node)? It covers the point made by emilio above.

[jakearchibald]

I don't mind too much between index(element) vs index-element().

CSS doesn't really allow you to interact with non-element nodes so adding something like index(node) would be pretty new/unusual.

[shshaw]

I like the flexibility of the `index()` and `count()` concept, especially if a selector could be passed in. A few possibilities that would be great to see: * `count(children)` for the number of child elements (akin to `count(“>*”)`) * `count(“.media”)` for counting the children matching a selector * `count(siblings)` for getting parent’s element count minus 1. * `index(siblings)` for getting the element’s index relative to its siblings * `index(n)` for getting the n value in :nth-child loops for more advanced selecting Imagine using `count()` to help you determine the number of `grid-columns`! I realize not all of those would be feasible or possible initially, but having open ended functions could allow their expansion in the future.