Writing Reusable Logic with Stylus Custom Functions

Problem: Repeating the Same Calculations in Your Stylesheet

When you need to compute values like responsive gutters, color shades, or complex spacing repeatedly, copying the same expression across many rules leads to duplication and makes updates error‑prone.

Thesis: Stylus custom functions let you encapsulate that logic once and reuse it anywhere a CSS expression is valid, keeping your stylesheet DRY and easier to maintain.

Defining a Simple Function

Use the function keyword, give it a name, list parameters, and return a value with return. The function is hoisted, so you can call it before its definition.

// file: utils.styl
function double($n)
  return $n * 2

// call before definition – works because of hoisting
margin: double(10px)  // → margin: 20px;

To see the result, compile the Stylus source:

# Run in a terminal with read/write access to the current directory
stylus utils.styl -o utils.css

Expected check: Open utils.css and verify it contains margin: 20px;. Risk: The -o flag will overwrite an existing utils.css; back it up if needed.

Leveraging Built‑In Operators, Conditionals, and Loops

Inside a function you can use any Stylus expression, enabling calculations that would be cumbersome to repeat.

// gutter based on column count (12‑column grid)
gutter($cols)
  $total = 12
  $width = 100% / $total
  return ($width * $cols) - ($width * 0.1)  // 10% gutter

.container
  width: gutter(8)  // → width: 66.6667% - 6.6667% = 60% (approx)

Compile as before and inspect the output; you should see a width value close to 60% (exact depends on precision).

Variadic Functions and the Rest Operator

Stylus supports variadic functions via ..., letting you accept an arbitrary number of arguments—useful for string joins, space‑separated lists, or generating complex values.

function join(...)
  return arguments.join('-')

.example
  content: join('foo', 'bar', 'baz')  // → content: foo-bar-baz;

Again, compile and confirm the generated CSS contains content: foo-bar-baz;.

Trade‑Offs and Limitations

• Compilation time: Complex functions with loops or heavy math can increase build duration, especially in large projects.
• Debugging: Stack traces point to the generated CSS, not the original Stylus source, making it harder to locate the faulty function call.
• Single‑value return: A function cannot emit multiple declarations; for multi‑property blocks you still need mixins or extends.

To mitigate, keep functions focused on a single calculation and profile your build if compile times become noticeable.

Actionable Closing

Start by extracting one repeated calculation into a custom function, compile, and verify the output. If the function proves useful, gradually replace other duplicated snippets. Monitor build times and consider splitting overly complex functions into smaller helpers. This approach gives you a maintainable stylesheet without sacrificing the power of Stylus’s expressive syntax.