Sass math.random() Function

What You’ll Learn

math.random() is a compile-time random helper in the sass:math module. You will learn both call shapes (decimal vs integer), the global random() alias, why values freeze into CSS, the deprecated unit-ignoring caveat on $limit, and five examples.

What Is math.random()?

Sometimes you want variety baked into generated CSS—slightly different opacities, random order values, or demo noise. Sass can roll those numbers while compiling. Official docs place math.random under Other Functions.

• math.random() → random decimal between 0 and 1 (exclusive of exact predictability)
• math.random(10) → random whole number from 1 to 10
• Each call / each compile can produce a different result

📝 Syntax

Load the math module, then call the function:

@use "sass:math";

math.random($limit: null)

Parameters

Return value

📦 Loading sass:math

Prefer the module API. Official docs also document a global name, random(), for older stylesheets.

// Recommended — namespaced
@use "sass:math";
$n: math.random();
$i: math.random(10);

// Optional — bring members into the current namespace
@use "sass:math" as *;
$n: random();

// Optional — custom namespace
@use "sass:math" as m;
$n: m.random(5);

// Legacy global name (still works in many setups)
$n: random(5);

📏 Limits, Units, and Deprecation

Pass a plain integer when you want 1…N. Official docs warn about units on $limit:

🛠 Compatibility

This is about Sass compilers, not browsers. The random value is chosen while compiling—browsers only see the finished number.

Examples Gallery

Each example uses @use "sass:math". Open View Compiled CSS for a sample output—your next compile will likely show different numbers.

@use "sass:math";

@debug math.random(); // e.g. 0.2821251858
@debug math.random(); // e.g. 0.6221325814

.fade {
  opacity: math.random();
}

.fade {
  opacity: 0.1846807275;
}

@use "sass:math";

@debug math.random(10);    // e.g. 4
@debug math.random(10000); // e.g. 5373

.card {
  z-index: math.random(10);
}

.card {
  z-index: 3;
}

@use "sass:math";

$roll: math.random(5);

.tile {
  order: $roll;
  z-index: $roll;
}

.tile {
  order: 1;
  z-index: 1;
}

@use "sass:math";

$jitter: math.random(); // 0…1

.badge {
  opacity: 0.7 + $jitter * 0.25; // about 0.7–0.95
  letter-spacing: #{0.02 + $jitter * 0.04}em;
}

.badge {
  opacity: 0.8461701819;
  letter-spacing: 0.0433872291em;
}

@use "sass:math";

// Avoid (warns: units currently ignored)
// $bad: math.random(100px);

// Prefer unitless limit, then attach units yourself if needed
$steps: math.random(8);
.spacer {
  margin-block: #{$steps * 4}px; // 4px…32px in 4px steps
}

.spacer {
  margin-block: 20px;
}

🚀 Real-World Use Cases

• Demo / marketing builds — slightly different opacities or orders each release.
• Placeholder galleries — random order / z-index for masonry-like tests.
• Design exploration — quick noise while prototyping tokens.
• Seeded-looking variety — store one roll and derive several properties from it.
• Teaching compile time — show that Sass numbers freeze into CSS.
• Not for live UX — use JavaScript when randomness must change after load.

⚠️ Common Pitfalls

• Expecting runtime changes — rebuild CSS to get new numbers.
• Calling twice by accident — store one result when values must match.
• Passing units to $limit — deprecated ignore-units behavior; use unitless limits.
• Limits below 1 — the integer form expects $limit ≥ 1.
• Using it for secure tokens — this is styling noise, not cryptography.

💡 Best Practices