Handling Dynamic Arguments in Stylus with Variadic Mixins

The problem with fixed mixin signatures

When building a CSS utility library, you often encounter a conflict between precision and flexibility. A mixin designed to handle a single property-value pair is clean, but it becomes a burden when you need to apply that same logic to three or four different properties at once. The alternative—creating separate mixins for different numbers of arguments—leads to redundant code and a fragile API.

The solution is the variadic mixin. By using the ... (rest) syntax, a Stylus mixin can capture an arbitrary number of trailing arguments into a single list. This allows you to build utilities that scale based on the caller's needs without changing the mixin definition. Because the Stylus compiler resolves these lists at build time, there is no runtime performance penalty in the resulting CSS.

Implementing rest parameters

In Stylus, any parameter declared with the ... suffix collects all remaining arguments passed to the mixin. This captured list can then be iterated over using a for loop or manipulated as a standard Stylus list.

These variadic parameters work in tandem with default values. You can define required or optional named parameters first, followed by the rest parameter. This ensures that the mixin has the essential data it needs while remaining open to additional inputs.

Composable abstractions and forwarding

One of the most powerful aspects of variadic mixins is the ability to forward arguments. When one variadic mixin calls another, the spread operator can pass the captured arguments along unchanged. This prevents the need to manually repack arguments into new lists, enabling a chain of composable abstractions.

To avoid syntax errors during development, ensure your editor supports the ... syntax. For example, the VS Code Stylus extension provides autocomplete for these parameters, which helps catch naming mismatches before the code reaches the compiler.

Example: A multi-property prefixer

A practical application is a vendor-prefixing helper that can process any number of property-value pairs in a single call. In this example, each argument is passed as a small list containing the property name and its value.

// Definition: accepts any number of pairs via $props...
prefixed($props...)
  for $pair in $props
    // Deconstruct the pair: [0] is property, [1] is value
    $prop = $pair[0]
    $val = $pair[1]
    -webkit-{$prop}: $val
    -moz-{$prop}: $val
    -ms-{$prop}: $val
    {$prop}: $val

// Usage: passing multiple property-value pairs as lists
.container
  prefixed((transform, rotate(45deg)), (user-select, none), (appearance, none))

In this configuration, the $props variable becomes a list of lists. The for loop iterates through each pair, emitting four CSS declarations per argument. This reduces the number of mixin calls in your stylesheets while maintaining a clean, declarative syntax.

Trade-offs and limitations

While flexible, variadic mixins introduce two primary risks: CSS bloat and debugging complexity.

• Output Volume: Because each argument expands into multiple CSS rules, a single variadic call with many arguments can significantly increase the size of the final CSS file.
• Traceability: Source maps often point to the line where the mixin is defined rather than the specific call site. This can make it difficult to determine which specific argument caused a layout issue when inspecting the compiled output.

Additionally, this feature requires Stylus version 0.50 or later. Attempting to use the ... syntax in older versions will result in a compilation error.

Verifying the implementation

Before deploying variadic mixins to production, verify your environment and output:

1. Check Version: Run stylus -v in your terminal. Ensure the version is 0.50+. This requires execute permissions for the Stylus binary.
2. Local Compilation: Create a test file (e.g., test.styl) with a simple variadic mixin. Compile it using stylus test.styl -o test.css and inspect the output to ensure the list expansion is correct.
3. Cross-Reference: Paste the code into the official Stylus Playground to confirm that the local compiler output matches the expected behavior of the language specification.