Proposal: Custom CSS Functions & Mixins

[mirisuzanne]

Background

Read the full explainer

There's an existing issue for Declarative custom functions, which forms the basis for much of this proposal. I'm opening a separate issue here, in order to make a broader proposal building on that, which includes both functions and mixins.

From a language perspective, mixins and functions are somewhat distinct – they live at different levels of the syntax, and come with different complications. It may make sense to handle them in different levels of a specification (likely functions first) or even different specifications altogether. Function-specific discussion could move back to the existing thread for that work. However, the features also have a lot in common from the author/syntax perspective, so I wanted to consider them together here, without cluttering the main thread.

Intro

Both Mixins and Functions provide a way to capture and reuse some amount of logic. That can be used for the sake of developer shorthands, and also as a way of ensuring maintainability by avoiding repetition and encouraging consistent use of best practice patterns. For many years, authors have been using pre-processors to perform this sort of CSS abstraction – or experimenting with custom property tricks like the space toggle hack, and recently style queries. There's also an open issue for Higher level custom properties with many mixin-like use-cases.

By providing a native CSS solution for these use-cases, we can help simplify web tooling/dependency requirements – while also providing access to new functionality. Mixins and functions in the browser should be able to accept custom property arguments, and respond to client-side media, container, and support conditions.

The overlapping syntax basics

Both functions and mixins need to be defined with a (custom-ident) name, a parameter-list, some amount of built-in-logic, and some output to return. The difference between the two is where they can be used in CSS, based on the type of output they provide:

• Functions return CSS values (like a string, color, or length) and can be used inside a CSS declaration
• Mixins return entire CSS declarations or even rule blocks (including selectors and other at-rules)

For the basics, I'm proposing two new at-rules following a similar pattern:

/* custom functions */
@function <name> [(<parameter-list>)]? {
  <function-logic-and-output>
}

/* custom mixins */
@mixin <name> [(<parameter-list>)]? {
  <mixin-logic-and-output>
}

The parameter lists should be able to define parameters with a (required) name, an (optional) default, and potentially (optional) <syntax>. In order to allow custom-property values with commas inside, we likely need a ; delimiter both in defining and passing arguments, where values are involved. To re-use existing custom-property syntax, we could do something like:

@function --example (--named-parameter; --name-with: default-value) { 
  /* if further description of a parameter is necessary */
  @parameter --named-parameter {
    default: 2em;
    syntax: "<length>";
  }
}

[Edited] @emilio has suggested potentially having parameter names only in the parameter list, and then @parameter-like rules in the body of the function/mixin when default values or syntax descriptor are needed. That would remove the need for ; delimiters in the prelude entirely. I'm not attached to all the details of the syntax here, but borrowed from existing structures. If we don't need the syntax definition for parameters, or can add that later, it might allow us to simplify further.

Internally, both syntaxes should allow conditional at-rules such as @media, @container, and @supports. That's one of the primary functions that CSS-based functions and mixins could provide. I don't think non-conditional or name-defining at-rules would serve any purpose, and should likely be discarded.

Functions

Normal properties inside a function would have no use, and could be discarded and ignored. However, it would be useful for functions to have internally-scoped custom properties. To avoid accidental conflicts, internal function logic would not have access to external custom properties besides the values explicitly passed in to the defined parameters.

In addition to allowing (scoped) custom properties and conditional at-rules, a function would need to define one or more resulting values to return. I like the at-rule (e.g. @return) syntax suggested in the original thread, though the result descriptor could also work. If more than one value would be returned, the final one should be used (to match the established last-takes-precedence rules of the CSS cascade).

An example function with some conditional logic:

@function --at-breakpoints(
  --s: 1em;
  --m: 1em + 0.5vw;
  --l: 1.2em + 1vw;
) {
  @container (inline-size < 20em) {
    @return calc(var(--s));
  }
  @container (20em < inline-size < 50em) {
    @return calc(var(--m));
  }
  @container (50em < inline-size) {
    @return calc(var(--l));
  }
}

h1 {
  font-size: --at-breakpoints(1.94rem, 1.77rem + 0.87vw, 2.44rem);
  padding: --at-breakpoints(0.5em, 1em, 1em + 1vw);
}

Functions would be resolved during variable substitution, and the resulting computed values would inherit (the same as custom properties).

Mixins

Mixins, on the other hand, will mostly contain CSS declarations and nested rules that can be output directly:

@mixin --center-content {
  display: grid;
  place-content: center;
}

body {
  @apply --center-content;
  /*
    display: grid;
    place-content: center;
  */
}

I don't believe there is any need for an explicit @return (though we could provide one if necessary). Instead, if there is any use for mixin-scoped or 'private' custom properties, we could consider a way to mark those specifically. Maybe a flag like !private would be enough?

Another possible example, for gradient text using background-clip when supported:

@mixin --gradient-text(
  --from: mediumvioletred;
  --to: teal;
  --angle: to bottom right;
) {
  color: var(--from, var(--to));

  @supports (background-clip: text) or (-webkit-background-clip: text) {
    --gradient: linear-gradient(var(--angle), var(--from), var(--to));
    background: var(--gradient, var(--from));
    color: transparent;
    -webkit-background-clip: text;
    background-clip: text;
  }
}

h1 {
  @apply --gradient-text(pink, powderblue);
}

---

There are still many issues to be resolved here, and some syntax that should go through further bike-shed revisions. Read the full explainer for some further notes, including a suggestion from @astearns for eventually providing a builtin keyframe-access mixin to help address the responsive typography interpolation use-case.

[andruud]

@function --at-breakpoints [...]

OK, that seems approachable. Having a @container as a conditional thing means we'll evaluate the container query (and other queries) later than usual, but I don't think it's substantially worse than container units, which already evaluate quite late.

Mixins return [...] rule blocks (including selectors and other at-rules)

[...] mixins [...] would be resolved during variable substitution

Those two things are not compatible. But it's possible that we'll able to impose enough restrictions on this to make it feasible, and still get something useful. For example, limit mixins to only declarations, or only declarations and nested &-rules (which would allow your nested @supports example).

including a suggestion from @astearns for eventually providing a builtin keyframe-access mixin to help address the #6245 (comment) use-case

That's an interesting idea. :-)

[lilles]

I think it will be hard to support @mixins with selectors inside the @mixin. Selectors are typically matched from right to left in impls and would be started inside the @mixin rule. If you have something like:

@mixin --foo {
  .a { }
}

.b {
  @apply --foo;
}

.c {
  @apply --foo;
}

In that case we would need to start matching from the .a in the mixin and branch out to the nested .b and .c selectors. This branch is dynamic based on how @mixin rules cascade. I think that is pretty hard to do in the current implementation in Blink. Especially for style invalidation, but also for efficient selector matching. The implicit & for @supports, @media, etc. should be fine.

It was not clear to me from the "Mixins, on the other hand, will mostly contain CSS declarations and nested rules that can be output directly" that nested selectors would be allowed, but the clearfix example in the full explainer uses nesting.

[mirisuzanne]

If nesting is possible it would be popular. Many existing mixins are used to establish things like consistent hover/focus handling (nested pseudo-classes) or like icon-buttons, including styles for the nested icon, etc.

(updated so that the variable-substitution reference is specific to functions)

[romainmenke]

I always saw @mixins more like syntactic sugar.

Where resolving would be roughly equivalent to wrapping in &{} and inserting that where @apply used to be.

Is there a specific use case where the result would be substantially different?

(I am definitely viewing this to much from the perspective of preprocessors.)

---

Edit :

(updated so that the variable-substitution reference is specific to functions)

ack

[lilles]

I always saw @mixins more like syntactic sugar.

Where resolving would be roughly equivalent to wrapping in &{} and inserting that where @apply used to be.

Is there a specific use case where the result would be substantially different?

That's a whole different story and much simpler to implement. It would not allow you to apply @mixins across stylesheets, which might be a showstopper?

[romainmenke]

It would not allow you to apply @mixins across stylesheets, which might be a showstopper?

That would be unfortunate. Dev tools will often bundle or chunk stylesheets in ways that aren't immediately clear or controllable by authors.

It would make mixins much harder to use.

[kizu]

Really happy to see this proposal! As an author, I always wanted to have mixins and functions in CSS, and can't wait for the day when we would get anything closer to it. I don't mind the exact syntax, so would mostly focus on features and usage.

To avoid accidental conflicts, internal function logic would not have access to external custom properties besides the values explicitly passed in to the defined parameters.

Is this a strong requirement? I can see a lot of use cases for the implicit access for external custom properties:

• Design-tokens. They could be potentially solved with env() in some cases, but not always: often the tokens could be calculated based on other custom properties, like a color token that chooses between a light and dark theme, and while it might be initially defined on the :root (or as env() in the future), there are use-cases when we override a whole group of tokens somewhere down the tree, like with a .dark-mode className.

  Our custom function could want to reuse such tokens, but if external custom properties are not available, that won't be possible. I'd propose making it so the custom properties defined inside the function (and as its parameters) to override the external custom properties.

  It would be up to authors to avoid the conflicts, and would be similar to how things work, for example, in JS, where we have access to the variables from the outer scope unless we would override them.

• “context”-like API. Custom properties have inheritance, which is very useful when you want to pass some values deep down some chain of elements.

  I can see how this aspect can be useful for functions as well: if we'd say something like “custom properties defined in a function body is scoped to everything inside that function, and is available inside any functions called inside the function body, overriding the external ones”. This would work similarly to how scopes and variables work in JS, for example, and would be how things would be expected to work.

Some other questions/thoughts, but very preliminary, as I would need to re-read the proposal (and I just skimmed the explainer for now, would need to read it properly) a few times and think long about it:

1. For mixins, I'll need to think more about them, but my main question: would we be able to somehow pass the return of one mixin as an argument to another? See “block mixins” from stylus, for example: https://stylus-lang.com/docs/mixins.html#block-mixins (Disclosure: I was a maintainer for Stylus for a while, and was behind some of its weirder features like block mixins (specs-wise, not implementation-wise), so I'm biased).

2. When thinking about functions and mixins, one thing that I immediately remember I wanted to have in CSS — an ability to have arrays/lists and maps. That might be worth a separate issue (maybe there was one? I did not yet try to find one), but in many many mixins in preprocessors developers are used to have some way of retrieving a value from a map, or manipulating a list of values. Again, this is probably a very separate topic, but I just have to mention it, as maybe having these in the back of our heads when thinking about mixins could help.

3. Similarly, with conditions in CSS. Having conditionals based on container-queries is good, but we'd for sure would want an ability to do things based on input conditionally, with value comparison etc. Again, probably a slightly separate thing, but I saw it was mentioned as a question in the explainer, so I want to mention it as something that I, as an author, would want to see possible eventually in CSS.

That's it for now. I would try to find time to read the whole explainer properly, and would come back with more feedback.

[mirisuzanne]

@lilles Some follow-up about nesting in mixins… I don't think that constraint would be a blocker for making this a useful feature. I'm curious if there's any useful distinction between between nested selectors that change the subject, and those that only add additional constraints? For example, selectors like & > p or & + p would require finding a new selector subject, while &:hover adds a constraint to the existing subject.

To avoid accidental conflicts, internal function logic would not have access to external custom properties besides the values explicitly passed in to the defined parameters.

Is this a strong requirement?

@kizu I would consider it a strong authoring requirement that nothing inside the function should have accidental consequences on values outside the function. I don't know that we need such a strong requirement in the other direction. I don't know if there would be implementation concerns about allowing external values into a function, but I think you're right that it could work for authoring.

1. […] would we be able to somehow pass the return of one mixin as an argument to another?

I'm not familiar with the feature in Stylus, but I think this is similar to the @content feature in Sass, and the similar feature discussed in the explainer?

Similarly, there's a section on argument conditions and loops – roughly your points 3 & 2, though I don't go into a lot of detail on lists/maps. In both cases, I considered them potential future extensions rather than essential aspects of a basic function/mixin feature.

[tabatkins]

First, I've talked this over with Miriam already, and broadly am happy with the elaboration on my earlier idea of making functions basically just "fancy variables".

---

Edited before posting: whoops, yeah, the edited version of argument syntax makes me a lot happier. I think we can still put syntax into the arglist, fwiw.

@function --foo (--bar "<string>", --baz "<number>") {...}

I think that still reads reasonably? And if it is too long and hard to read, you can always move it to @parameters.

(I presume that anything without a default value would be a required arg, making the function invalid if not passed? Since args in the arglist wouldn't have a default, that would match up with the usual practice of required args coming first, followed by optional args.)

---

To avoid accidental conflicts, internal function logic would not have access to external custom properties besides the values explicitly passed in to the defined parameters.

I disagree with this, and think it's probably pretty important to allow functions to access the variables present on the element. I don't see any way for there to be an accidental conflict; every name that could potentially conflict is function-local and controlled by the function author, no?

Tho, hm, we'd have to be a little careful about nested functions. If we did make ambient variables available we'd have to decide whether all functions saw the element's vars, or saw the function's vars too. The latter does have an accidental shadowing concern.

But I feel like it's important to allow this, because otherwise you can't replace existing variables (that reference other vars) with functions unless you explicitly pass those variables, which can be annoying. In particular, it means you couldn't use custom units unless they were explicitly passed to the function, which feels extra-obnoxious.

However, it would be useful for functions to have internally-scoped custom properties.

Yes, this sounds great. Temp vars are useful.

Internally, both syntaxes should allow conditional at-rules such as @media, @container, and @supports. That's one of the primary functions that CSS-based functions and mixins could provide.

I agree that these are useful, but their usefulness isn't specific to functions. We've talked about a media() function that lets you do MQ-specific value resolution; should we just rely on that rather than having a special syntax just for functions?

(I'm not particularly against doing the @return and allowing conditional rules, fwiw. Just wondering if it would be better to lean on the generic functionality.)

---

Unmentioned here is what to do about recursive functions. Without the ability to test and branch on the value of one of the input variables, I think a recursive call is guaranteed to be cyclic just like a custom-property self-reference is, right? So presumably that should be detected and auto-failed using the existing anti-cyclic variable tech. If we later allow for the possibility of useful recursion we can relax the requirement and impose a stack limit or something. (Then we can repeat the TC39 arguments about tail recursion, yay!)

[mirisuzanne]

I presume that anything without a default value would be a required arg, making the function invalid if not passed?

I would not presume that, since guaranteed invalid is a reasonable default value. Is there a strong reason that should need to be specified explicitly in an @parameter rule?

think it's probably pretty important to allow functions to access the variables present on the element.

I'm open to this. As mentioned above, my stronger concern is that changes to an external variable don't accidentally escape the function.

Internally, both syntaxes should allow conditional at-rules such as @media, @container, and @supports. That's one of the primary functions that CSS-based functions and mixins could provide.

I agree that these are useful, but their usefulness isn't specific to functions. We've talked about a media() function that lets you do MQ-specific value resolution; should we just rely on that rather than having a special syntax just for functions?

That comment was not about a special syntax for functions, but a normal syntax allowed inside functions. The only potential need for a special syntax would be if we want to allow some (restricted) parameters in function at-rules. But this proposal does not include that as an initial requirement. (It's also not specific to the @return syntax, but should work no matter how the returned value is declared).

[jimmyfrasche]

Functional languages tend to have a 'let' <vars>+ 'in' <expr> syntactic form whose result is <expr> which can make use of the 1 or more <vars> that are private to the let-expression.

I've wanted CSS functions for a long time but some of the places I've wanted them I'd only use it once so I could reuse internal computations without leaking a lot of one-time custom properties (my solution in practice is to just shrug and leak a lot of one-time custom properties and hope it doesn't cause any problems later).

If there were a CSS version of let-expressions you could just tell people using functions to use that if they need private stuff and it would be handy for the odd case where you have a handful of things you want to refer to more than once but a function would be overkill.

[tabatkins]

Mixins return [...] rule blocks (including selectors and other at-rules)

[...] mixins [...] would be resolved during variable substitution

Those two things are not compatible. But it's possible that we'll able to impose enough restrictions on this to make it feasible, and still get something useful. For example, limit mixins to only declarations, or only declarations and nested &-rules (which would allow your nested @supports example).

Right, I assumed that they'd be applied before any value stages, essentially equivalent to doing a preprocessor. As far as I can tell there's nothing dynamic about mixins (save the values passed in themselves, but they're effectively just uniquely-named variables). (And note that we already established, back in the last attempt at @apply, that passing around declaration blocks via computed values is not viable.)

That, I think, would allow us a lot of freedom in what to allow inside the mixin without adding a lot of complexity. However, it limits our ability (somewhat) to do branching/etc based on the values. We could still do, say, a @for based on a static value (like @apply --foo(5)), but not on a dynamic one (like @apply --foo(var(--bar)) or @apply --foo(counter(list-item)). But that's something to worry about in the future; we're not doing conditionals or loops yet.

[tabatkins]

I would not presume that, since guaranteed invalid is a reasonable default value.

Sure, but we could spell that initial, like @parameter --optional { default: initial; }.

And it's not a reasonable default value if you have a syntax. Without the "required" behavior, we'd have to require that with a syntax you also have to provide an initial value.

As mentioned above, my stronger concern is that changes to an external variable don't accidentally escape the function.

Agreed, that's definitely required, but I don't think anything could reasonably cause that. You can't affect any properties on the element from within a function.

[stuff about conditionals]

Yeah, I don't have an issue with the proposal, was just thinking aloud. I think doing conditionals as proposed is better (plus we don't have a plan for an inline CQ function anyway).

[lilles]

@lilles Some follow-up about nesting in mixins… I don't think that constraint would be a blocker for making this a useful feature. I'm curious if there's any useful distinction between between nested selectors that change the subject, and those that only add additional constraints? For example, selectors like & > p or & + p would require finding a new selector subject, while &:hover adds a constraint to the existing subject.

I don't think that would be different. The common thing is that nesting in this case dynamically combines parts of the selectors from the mixin and the apply and that would require the implementations to connect those pieces at a later stage than the parser, and that the multiple applications branch into multiple ancestor selectors. For nesting it's much easier since it's done at parse time and the selector representation can be fully built at parse time.

How complicated and how much of a re-organization of the selector matching/invalidation code this is depends when we can resolve the mixin applications.

[lilles]

Mixins return [...] rule blocks (including selectors and other at-rules)
[...] mixins [...] would be resolved during variable substitution

Those two things are not compatible. But it's possible that we'll able to impose enough restrictions on this to make it feasible, and still get something useful. For example, limit mixins to only declarations, or only declarations and nested &-rules (which would allow your nested @supports example).

Right, I assumed that they'd be applied before any value stages, essentially equivalent to doing a preprocessor. As far as I can tell there's nothing dynamic about mixins (save the values passed in themselves, but they're effectively just uniquely-named variables). (And note that we already established, back in the last attempt at @apply, that passing around declaration blocks via computed values is not viable.)

IIUC, it is a requirement that mixins can be applied across stylesheets, so that the connection between the mixin and the apply has to be re-done as new stylesheets are added and requires some cascade order definition for which mixin is found first for a given name.

As mentioned in a different post I think this can be challenging for an implementation if we allow selectors inside the mixin. At least if the mixin contains a selector which becomes part of multiple nested selectors.