CSS random() reference doc

files/en-us/glossary/rng/index.md

@@ -18,6 +18,6 @@ Most PRNGs are not cryptographically secure.
 
 ## See also
 
-- [Pseudorandom number generator](https://en.wikipedia.org/wiki/Pseudorandom_number_generator) on Wikipedia
-- {{jsxref("Math.random()")}}, a built-in JavaScript PRNG function. Note that this is not a cryptographically secure PRNG.
+- JavaScript's {{jsxref("Math.random()")}} and CSS's {{cssxref("random()")}} built-in PRNG functions. Note that these are not a cryptographically secure PRNG.
 - {{domxref("Crypto.getRandomValues()")}}: this is intended to provide cryptographically secure numbers.
+- [Pseudorandom number generator](https://en.wikipedia.org/wiki/Pseudorandom_number_generator) on Wikipedia

files/en-us/web/css/guides/values_and_units/index.md

@@ -44,6 +44,7 @@ Every CSS declaration consists of a property/value pair. The value can take vari
 - {{cssxref("mod()")}}
 - {{cssxref("pow()")}}
 - {{cssxref("progress()")}}
+- {{cssxref("random()")}}
 - {{cssxref("rem()")}}
 - {{cssxref("round()")}}
 - {{cssxref("sibling-count()")}}
@@ -54,7 +55,7 @@ Every CSS declaration consists of a property/value pair. The value can take vari
 - {{cssxref("tan()")}}
 - {{cssxref("url_function", "url()")}}
 
-The CSS values and units module also introduces the `calc-mix()`, `crossorigin()`, `first-valid()`, `integrity()`, `random()`, `random-item()`, `referrerpolicy()`, `src()`, `type()`, and `toggle()` functions. Currently, no browsers support these features.
+The CSS values and units module also introduces the `calc-mix()`, `crossorigin()`, `first-valid()`, `integrity()`, `random-item()`, `referrerpolicy()`, `src()`, `type()`, and `toggle()` functions. Currently, no browsers support these features.
 
 ### Data types
 

files/en-us/web/css/reference/values/random/index.md

@@ -0,0 +1,303 @@
+---
+title: random()
+slug: Web/CSS/Reference/Values/random
+page-type: css-function
+status:
+  - experimental
+browser-compat: css.types.random
+sidebar: cssref
+---
+
+The **`random()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/Reference/Values/Functions) generates a random value within a specified range, optionally limiting the possible values to step size intervals between those limits. The `random()` function can be used when specifying a {{CSSxRef("<length>")}}, {{CSSxRef("<frequency>")}}, {{cssxref("angle")}}, {{CSSxRef("<time>")}}, {{CSSxRef("<resolution>")}}, {{CSSxRef("<percentage>")}}, {{CSSxRef("<number>")}}, or {{CSSxRef("<integer>")}} within a property value.
+
+{{InteractiveExample("CSS Demo: random()")}}
+
+```html interactive-example
+<div class="box"></div>
+```
+
+```css interactive-example
+.box {
+  rotate: random(element-shared, 0deg, 360deg);
+  width: random(element-shared, 50px, 300px);
+  background-color: hsl(random(element-shared, 0, 360) 50% 50%);
+  height: random(element-shared, 50px, 300px);
+}
+
+@supports not (order: random(1, 2)) {
+  body::before {
+    content: "Your browser doesn't support the random() function.";
+  }
+}
+```
+
+## Syntax
+
+```css
+/* Basic usage */
+random(0, 100)
+random(10px, 500px)
+random(0deg, 360deg)
+
+/* With step interval */
+random(0, 100, 10)
+random(0rad, 1turn, 30deg)
+
+/* With base value */
+random(auto, 0, 360)
+random(element-shared, 0s, 5s)
+random(--unique-base, 400px, 100px)
+random(fixed 0.5, 1em, 40vw)
+random(--unique-base element-shared, 100dpi, 300dpi)
+
+/* With base and step values */
+random(element-shared, 0deg, 360deg, 45deg)
+random(--my-base, 1em, 3rem, 2px)
+```
+
+### Parameters
+
+- `<random-value-sharing>` {{optional_inline}}
+  - : Controls which random functions in the document will share a random base value and which will get distinct values.
+    This can be one of the following values, or both a custom key and the keyterm `element-shared`, separated by a space:
+    - `auto`
+      - : Each use of `random()` in an element's style gets its own unique random base value.
+    - {{cssxref("dashed-ident")}}
+      - : A custom key for sharing (e.g., `--my-random-key`) the same random base value across properties of an element.
+    - `element-shared`
+      - : A random base value is shared across all elements for the same property using this key term. This base value is independent from the `random()` functions included in the values of other properties on that same element, unless the random functions also include the same custom key.
+    - `fixed <number>`
+      - : Specifies a base value between `0` and `1`, inclusive, for the random value to be generated from.
+
+- `<calc-sum>, <calc-sum>`
+  - : Two required, comma-separated, `<number>`, `<dimension>`, or `<percentage>` values, or calculations resolving to one of these types, defining the minimum and maximum values, respectively. Both values must be resolvable the same [data type](/en-US/docs/Web/CSS/Reference/Values/Data_types). If the second `<calc-sum>` is less than the first `<calc-sum>`, the function will return the first `<calc-sum>`.
+
+- `<calc-sum>` {{optional_inline}}
+  - : The optional third `<calc-sum>`, preceded by a comma, specifies the step interval. If present, and of the same data type as the two comma-separated minimum and maximum `<calc-sum>` values, it defines the return value to be minimum value or at increments of the step value from the minimum value, up to the maximum value.
+
+### Return value
+
+Returns a random `<number>`, `<dimension>`, or `<percentage>` between the minimum and maximum range values, inclusive, in the same type as the `<calc-sum>` parameters.
+
+## Description
+
+The `random(SEED, MIN, MAX, STEP)` function specifies the minimum and maximum values and optional step increments, starting at the minimum value. The function generates a random result within the range specified. The seed, an [optional `<random-value-sharing>`](#random-value-sharing) parameter, enables sharing or varying random base values across different properties and elements.
+
+The minimum, maximum and step values specified must be of the same data type for the function to be valid. While the units in the two to three `<calc-sum>` parameters don't need to be the same, they do need to be of the same data type, such as {{cssxref("number")}}, {{cssxref("percentage")}}, {{cssxref("length")}}, {{cssxref("angle")}}, {{cssxref("time")}}, or {{cssxref("frequency")}}, to be valid.
+
+### Random base value
+
+The random base value works like a [seed for randomness](/en-US/docs/Glossary/RNG). It's a starting number that is used to generate the final random result. When two `random()` functions share the same base value, their results vary together in a predictable pattern. When they have different base values, their results are completely independent of each other.
+
+The optional first`<random-value-sharing>` parameter controls how the random base value is shared. Sharing enables reusing the same randomly generated value, a necessity for some design effects. The value can be set to use `auto`, an `element-shared` keyword, a custom {{cssxref("dashed-ident")}} , or `fixed <number>`. Including a custom {{cssxref("dashed-ident")}} with the `element-shared` keyword, space-separated, is also valid.
+
+#### The `element-shared` keyword
+
+All the `random()` functions with the `element-shared` keyword share the random base value for the other elements but only for the same property. For example, when the following is declared, A, B, and C will be identically sized rectangles with all the same random width and all the same random height:
+
+```css
+A,
+B,
+C {
+  width: random(element-shared, 10px, 200px);
+  height: random(element-shared, 10px, 200px);
+}
+```
+
+#### Custom names
+
+When you specify a `<dashed-ident>` (e.g., `--custom-name`), each element in an element's styles with the same name shares the same random base value, and ones with different `<dashed-ident>` values will be assigned distinct random base values. When the following is declared, A, B, and C will all be squares, because within each element, all properties that reference the same ident will share the same base value. Therefore, the width of each will be the same as it's height. Note that, in this case, A, B, and C will have distinct sizes because the sharing between properties of an element, not between elements.
+
+```css
+A,
+B,
+C {
+  width: random(--custom-name, 10px, 200px);
+  height: random(--custom-name, 10px, 200px);
+}
+```
+
+#### Setting both `<dashed-ident>` and `element-shared`
+
+Combining a `<dashed-ident>` with `element-shared` (e.g., `random(--custom-name element-shared, 0, 100)`) shares the random base value across elements and properties that use the same `<random-value-sharing>` parameter. Given the following, A, B, and C will all be squares of the same size:
+
+```css
+A,
+B,
+C {
+  width: random(--custom-name element-shared, , 10px, 200px);
+  height: random(--custom-name element-shared, 10px, 200px);
+}
+```
+
+#### Automatic behavior
+
+When the first parameter is omitted, or explicitly set to `auto`, an ident is auto-generated from the property name and position. This behavior can cause some unexpected random base value sharing.
+
+```css
+.foo {
+  width: random(100px, 200px);
+}
+.foo:hover {
+  width: random(100px, 200px);
+}
+.bar {
+  margin: random(1px, 100px) random(1px, 100px);
+}
+.bar:hover {
+  margin: random(1px, 100px) random(1px, 100px) random(1px, 100px)
+    random(1px, 100px);
+}
+```
+
+When the seed defaults or is explicitly set to `auto`, the user agent auto-generates a seed name following consistent rules based on property name and order. Because of this, `random()` functions end up with the same random base value. In this example, the generated value sharing identifier is the same for `.foo` and `.foo:hover` width values, so the value won't change between states. Similarly, the first two random values in the `margin` declaration will be unchanged when hovered, so `bar`'s top and right margins will remain the same, but the bottom and left margins will get independent random values on hover. To get an independent value for each `random()` function, provide a unique {{cssxref("dashed-ident")}}.
+
+### Custom properties
+
+As with all CSS functions, when a `random()` function is included within a custom property value, the value remains a function; behaving like a text replacement mechanism, not storing a single return value.
+
+```css
+--random-size: random(1px, 100px);
+```
+
+In this example, the `--random-size` custom property does not "store" the randomly generated result. When `var(--random-size)` is parsed it is effectively replaced with `random(1px, 100px)`, meaning each use creates a new `random()` function call with its own base value depending on the context in which its used.
+
+This is not true in the case of using `random()` when registering a custom property with {{cssxref("@property")}}. Registered custom properties compute random values and store them. In this example, A, B, and C will be squares of equal size:
+
+```css
+@property --defaultSize {
+  syntax: "<length> | <percentage>";
+  inherits: true;
+  initial-value: random(100px, 200px);
+}
+:root {
+  --random-angle: random(0deg, 360deg);
+}
+A,
+B,
+C {
+  background-color: hsl(var(--random-angle) 100% 50%);
+  height: var(--defaultSize);
+  width: var(--defaultSize);
+}
+```
+
+## Accessibility
+
+Because `random()` can generate an unknown value within a range, you don't have full control over what you get. This can lead to inaccessible results. For example, if you use `random()` to generate text color, you could end up with a value that has low contrast with its background. It is important to be mindful of the context in which `random()` is used, ensuring your results are always accessible.
+
+## Formal syntax
+
+{{CSSSyntax}}
+
+## Examples
+
+### Basic Usage
+
+In this example, we'll generate random colors for some circular badges to demonstrate the basic usage of the `random()` function.
+
+#### HTML
+
+We include five badges, one using the `desaturated` class and two using the `unique` class.
+
+```html
+<div class="badge"></div>
+<div class="badge"></div>
+<div class="badge desaturated"></div>
+<div class="badge unique"></div>
+<div class="badge unique"></div>
+```
+
+#### CSS
+
+We render the five badges as circles. We use the `random()` function within an {{cssxref("hsl()")}} color function to define the {{cssxref("angle")}} of the {{cssxref("hue")}}. We set `element-shared` to share the random base value between the default `badge` and the `desaturated` one, so it is a less saturated version of the same {{cssxref("hue")}}. We then override the `unique` badges to have a truly random `hue` by letting the base value sharing parameter default to `auto`.
+
+```css
+.badge {
+  display: inline-block;
+  width: 5em;
+  aspect-ratio: 1/1;
+  border-radius: 50%;
+  background: hsl(random(element-shared, 0, 360) 50% 50%);
+}
+.badge.desaturated {
+  background: hsl(random(element-shared, 0, 360) 10% 50%);
+}
+.badge.unique {
+  background: hsl(random(0, 360) 50% 50%);
+}
+
+@supports not (order: random(1, 2)) {
+  :root::after {
+    content: "Your browser doesn't support the random() function.";
+  }
+}
+```
+
+#### Result
+
+{{EmbedLiveSample('Generate random colors for circular badge', '100%', '300px')}}
+
+### Creating a starry backdrop
+
+#### HTML
+
+```html
+<html>
+  <body>
+    <div class="particle"></div>
+    <div class="particle"></div>
+    <div class="particle"></div>
+    <div class="particle"></div>
+    <div class="particle"></div>
+  </body>
+</html>
+```
+
+#### CSS
+
+```css
+body {
+  background: black;
+}
+
+.particle {
+  border-radius: 50%;
+  background: white;
+  position: fixed;
+  width: random(--particle-size, 0.25em, 1em);
+  height: random(--particle-size, 0.25em, 1em);
+  top: random(0%, 100%);
+  left: random(0%, 100%);
+  animation: move 1s alternate-reverse infinite;
+}
+```
+
+```css hidden
+@supports not (order: random(1, 2)) {
+  body::before {
+    color: white;
+    content: "Your browser doesn't support the random() function.";
+  }
+}
+```
+
+#### Result
+
+{{EmbedLiveSample('Creating a starry backdrop', '100%', '300px')}}
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{cssxref("calc()")}}
+- {{domxref("Math.random()")}}
+- [CSS units and values](/en-US/docs/Web/CSS/Guides/Values_and_units) module
+- [Rolling the Dice with CSS random()](https://webkit.org/blog/17285/rolling-the-dice-with-css-random/) via webkit.org (2025)
+- [CSS Almanac: random()](https://css-tricks.com/almanac/functions/r/random/) via CSS-Tricks.com