Declarative custom functions

[johannesodland]

@tabatkins mentioned the idea of declarative custom functions in a comment on the custom units issue:

Like, pretend for a moment that we have simple custom functions, like:

@custom-function --fluid(--value) {
  arg-syntax: --value "<number>";
  result: clamp(1rem, var(--value) * 1vw, var(--value) * 1rem);
}

This seems too good to not follow up on. Custom functions would make it possible to write more readable css with less repetition.

Background

We can already increase readability and reduce repetition of expressions by using function like custom properties, as @mirisuzanne describes in her excellent article on CSS Custom Properties In The Cascade. This is available in browsers today.

There are however limits to what we can do with function-like custom properties, and there are issues with their readability.

Example
The following expression returns 0% at a minimum viewport size of 375px, and 100% at a maximum viewport size of 1920px.

clamp(0%, 100% * (100vw - 375px) / (1920px - 375px), 100%)

We could give this expression semantic meaning and reuse it almost everywhere by declaring it as the value of a custom property:

* {
    --min-width: 0px;
    --max-width: 2560px;
    --fluid-ratio: clamp(0%, 100% * (100vw - var(--min-width)) / (var(--max-width) - var(--min-width)), 100%);
}

This custom property could then be used with "arguments" where needed:

p {
  --min-width: 375px;
  --max-width: 1920px;
  font-size: mix(var(--fluid-ratio), 1rem, 1.25rem);
}

This is great, and should work in browsers today (except for divide by unit, that is specified in css-units-4 but not supported yet).

There are some limitations to this approach:

1. It's not possible to read from the rule that --min-width and --max-width are arguments for --fluid-ratio, nor that --fluid-ratio is a function like custom property.
2. We would run into trouble if we wanted to reuse the same "function" with separate parameters.

p {
  /* This would not work. (Arguably a constructed example) */
  --min-width: 375px;
  --max-width: 1920px;
  font-size: mix(var(--fluid-ratio), 1rem, 1.25rem);

  --min-width: 375px;
  --max-width: 700px;
  padding: mix(var(--fluid-ratio), 1rem, 2rem);
}

Proposal

Updated based on feedback. The original text is available below for context.

Add syntax for declarative custom functions. The syntax could follow the example from @tabatkins comment with an at-rule to declare the function and the syntax of its arguments:

@custom-function --fluid-ratio(--min-width "<length>", --max-width "<length>") {
   result: clamp(0%, 100% * (100vw - var(--min-width)) / (var(--max-width) - var(--min-width)), 100%);
} 

This would work through regular var substitution with a slightly different handling of the arguments. The custom function could then be used anywhere a var function can be used:

p {
  font-size: mix(--fluid-ratio(375px, 1920px), 1rem, 1.25rem);
  padding: mix(--fluid-ratio(375px, 700px), 1rem, 2rem);
}

As this is based on variable substitution it is not limited to math functions and can return any value. It could be used to return one of background patterns from @LeaVerou's pattern gallery:

@custom-function --checkerboard(--size "<length>") {
   result: linear-gradient(
        45deg,
        silver 25%,
        transparent 25%,
        transparent 75%,
        silver 75%
      )
      0px 0px / var(--size) var(--size),
    linear-gradient(
        45deg,
        silver 25%,
        transparent 25%,
        transparent 75%,
        silver 75%
      )
      calc(var(--size) / 2) calc(var(--size) / 2) / var(--size) var(--size);
}

.used {
  background: --checkerboard(32px);
}


There's an existing proposal for JS backed custom functions in Houdini. This proposal is related and would be a simple declarative version of that proposal, where in Houdini the substituted value would be provided by JS.










Original proposal text











### Proposal

Add syntax for declarative mathematical functions. The syntax could follow the example from @tabatkins comment with an at-rule to declare the function and the syntax of its arguments:

@custom-function --fluid-ratio(--min-width, --max-width) {
   arg-syntax: --min-width "<length>", --max-width "<length>";
   result: clamp(0%, 100% * (100vw - arg(--min-width)) / (arg(--max-width) - arg(--min-width)), 100%);
} 

The custom function could then be used where mathematical expressions can be used:

p {
  font-size: mix(--fluid-ratio(375px, 1920px), 1rem, 1.25rem);
  padding: mix(--fluid-ratio(375px, 700px), 1rem, 2rem);
}

There are probably many reasons why this would be annoying or impossible to implement, but hopefully there's smarter people than me out there that can come up with a way to solve custom functions.




[dbaron]

I'd assume that the argument syntax validation would match what's done for @property. If that's the case, I don't immediately see anything that would make this particularly difficult.

One issue that might (but I'm not sure) be difficult (although maybe more for designing/specifying the feature than for implementing it) is determining when the functions are resolved. (Does it work like calc() and depend on what the arguments are?)

The syntax you propose seems generally reasonable, although there are various ways it could be changed. For example, I probably wouldn't do both of requiring -- for the arguments and requiring references to them be in an arg() function, but we probably do want at least one or the other, or something like them. (I think I'd lean towards not using the --, and keeping arg().)

There's also a question of whether this could interact with features like inherit, initial, or more advanced extensions like that proposed in #2864. (That is, whether the result could use those things.)

[bkardell]

Somewhat related, maybe? depending on how you squint at it? w3c/css-houdini-drafts#857

[johannesodland]

Somewhat related, maybe? depending on how you squint at it? w3c/css-houdini-drafts#857

Definitely. Thanks for pointing me to that issue 🙏🏼

I think the main difference was that this proposal was limited to mathematical or "pure" functions. They could be defined directly in css, and I hoped they could be easier to implement and polyfill than fully-fledged functions.

The houdini proposal is much more powerful and would allow you to back the custom functions with js.

I don't think there's a need for both custom mathematial functions, and proper/complex custom functions. Closing this issue, hoping that there will be a way to declare simple functions directly in css once the css-functions-api is drafted up.

[bkardell]

fwiw, my intent wasn't to suggest that this issue should be closed, but rather to link up history and use cases I was aware of so that it's easy to keep it all in mind.

[dbaron]

Yeah, I agree that this is worth keeping open in case we want to do this first.

[tabatkins]

One issue that might (but I'm not sure) be difficult (although maybe more for designing/specifying the feature than for implementing it) is determining when the functions are resolved. (Does it work like calc() and depend on what the arguments are?)

It would just be variable substitution, nothing more, nothing less. (Well, something more - we validate the arguments per the syntax as a help to the author, identical to registered properties. So still "just" variable substitution.)

The fact that the OP example is a math function has nothing to do with the custom function part, it just means that when it var-substitutes you get left with a math function, same as --foo: clamp(...); width: var(--foo);. This is just var substitution with some "time-of-use" subs (the arguments) rather than "time of definition" subs (what you'd get today if you tried to do something similar with custom properties).

[stuff about arg()]

My suggested syntax just used var() and normal custom property names for simplicity, and to underscore the fact that this is just var substitution under the covers. It also means you get the same var() behaviors you'd get elsewhere, like the ability to specify fallback values (useful if the argument doesn't match its declared syntax, as it'll sub the guaranteed-invalid value otherwise, per standard variable rules).

That said, it's possible we may want to do smarter stuff for the arguments, in which case it would make sense to have a different function. I just can't come up with any "smarter stuff" yet.

(That is, whether the result could use [initial, inherit, etc].)

That's the nice thing about making it just a slightly special case of variable substitution - we've already got answers to those questions. ^_^

Somewhat related, maybe? depending on how you squint at it? w3c/css-houdini-drafts#857

Definitely related. This would be a simple declarative version of the more full-featured, JS-driven Houdini feature linked there. I imagine they'd live in the same namespace and registered Houdini functions override @function declarations of the same name. They should already have similar behavior in many respects; that is, the Houdini feature will also be essentially just variable substitution, but with JS providing the substitution value.

[johannesodland]

I tried to update the proposal text based on the feedback and my (hopefully) improved understanding:

• This would work through var substitution. I updated the text to reflect that.
• It is not limited to math functions. I updated the title and added an example.
• It is related to the Houdini issue. Added some text and a link.
• Using custom syntax for args is not needed. Replaced it with var() functions.

The original text is left in an expandable details element for context.

[johannesodland]

Do we need initial argument values for when the function is referenced with too few arguments?

I think it would be sufficient if the initial values of arguments always are guaranteed-invalid value?

Providing an argument with wrong syntax would also result in a guaranteed-invalid value at compute time, so I guess it would be fine if both "missing argument" and "wrong argument" resulted in the same guaranteed-invalid value?

example: initial values for arguments

@custom-function --double-length(--length) {
   arg-syntax: --length "<length>";
   /* could be ambiguous with multiple arguments (i.e. one is "<length>#") */
   arg-initial-values: 0px; 
   result: calc(2 * var(--length, 20px));
} 

.use {
   height: --double-length(); /* 0px */
   width: --double-length(red); /* 40px */
}

example: missing arguments results in guaranteed-invalid values

@custom-function --double-length(--length) {
   arg-syntax: --length "<length>";
   result: calc(2 * var(--length, 20px));
} 

.use {
   height: --double-length(); /* 40px */
   width: --double-length(red); /* 40px */
}

[johannesodland]

Is there a need for a result syntax and a fallback value?

If declarative custom functions were to be used in animations, the result should have a declared syntax.

In addition, one should probably be able to provide a fallback value if the result expression is invalid.

@custom-function --flat-color(--color) {
   arg-syntax: --color "<color>";
   result: var(--color), var(--color);
   result-syntax: "<color>#";
   fallback: red, red;
} 

.valid-use {
   background: linear-gradient(--flat-color(green)); /* green */
}

.invalid-use {
   background: linear-gradient(--flat-color()); /* red */
}

Would a single space be allowed as an argument, similar to a space in a custom property declaration?

--valid-declaration: ; /* single whitespace */

@custom-function --identity(--input) {
   arg-syntax: --input "*";
   result: var(--input);
}

.use {
   --valid-declaration: ; /* single whitespace */
   --also-valid-declaration: --identity( ); /* single whitespace */
   --invalid-declaration: --identity(); /* no argument, guaranteed-invalid */
}

If so, I guess this could be used to create an --if-else function using the space toggle trick (not that we want to do this):

@custom-function --if-else(--condition, --result-if-true, --result-if-false) {
   arg-syntax: --condition "*", --result-if-true "*", --result-if-false "*";
   result: var(--condition) var(--result-if-true);
   result-syntax: "*";
   fallback: var(--result-if-false);
} 

.use-with-true-condition {
   background: --if-else( , green, red); /* green */
}

.use-with-false-condition {
   background: --if-else(initial, green, red); /* red */
}

[johannesodland]

Another question, sorry for the spam:

Would the initial value of result be the guaranteed-invalid value?

So that you could declare a function that always returned invalid?

@custom-function --invalid() {
   result: initial;
   /* 
   if there is a return-syntax, that would probably have to be the universal syntax definition 
   to skip fallback and allow result to return the initial `guaranteed-invalid value`*/
   result-syntax: "*"; 
} 

/* So that this */
.with-custom-function {
   some-prop: --invalid(); /* Guaranteed invalid value */
}

/* Would be equal to this */
.with-custom-prop {
  --invalid: initial;
  some-prop: var(--invalid); /* Guaranteed invalid value */
}

[johannesodland]

Another question regarding argument syntax. (sorry).

Is there anything stopping us from declaring the syntax inline with the arguments?

/* Could we do this (inline) */
@custom-function --sum(--argument1 "<number>", --argument2 "<number>") {
   result: calc(var(--argument1) + var(--argument2));
} 

/* Instead of this? (separate syntax declaration) */
@custom-function --function(--argument1, --argument2) {
   arg-syntax: --argument1 "<number>", --argument2 "<number>";
   result: calc(var(--argument1) + var(--argument2));
}