CSS random() reference doc

[jdatapple]

Description

Adds reference documentation for the CSS random() function.

Motivation

This new CSS function has shipped in Safari 26.2.

Additional details

See Safari 26.2 Release Notes

[github-actions]

Preview URLs (3 pages)

• /en-US/docs/Glossary/RNG
• /en-US/docs/Web/CSS/Guides/Values_and_units
• /en-US/docs/Web/CSS/Reference/Values/random

Flaws (7)

Note! 2 documents with no flaws that don't need to be listed. 🎉

Found an unexpected or unresolvable flaw? Please report it here.

URL: /en-US/docs/Web/CSS/Reference/Values/random
Title: random()
Flaw count: 7

• broken_links:
  • Link /en-US/docs/Web/CSS/dashed-ident is a redirect
  • Link /en-US/docs/Web/CSS/number is a redirect
  • Link /en-US/docs/Web/CSS/number is a redirect
  • Link /en-US/docs/Web/CSS/dimension is a redirect
  • Link /en-US/docs/Web/CSS/percentage is a redirect
• macros:
  • Macro cssxref produces link /en-US/docs/Web/CSS/hsl which doesn't resolve
  • Macro domxref produces link /en-US/docs/Web/API/Math/random which doesn't resolve

External URLs (3)

URL: /en-US/docs/Glossary/RNG
Title: Random Number Generator

• https://en.wikipedia.org/wiki/Pseudorandom_number_generator (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/CSS/Reference/Values/random
Title: random()

• https://css-tricks.com/almanac/functions/r/random/ (1 time) (Note! This may be a new URL 👀)
• https://webkit.org/blog/17285/rolling-the-dice-with-css-random/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2026-03-10 11:38:14)

[Josh-Cena]

Drive-by: I don't see it very clearly mentioned if the random() function ever gets reevaluated, and if so, when. IIUC, this is the first non-idempotent function in CSS, right?

[estelle]

I reviewed the first half. i'll finish tomorrow. I made a lot of suggestions in hopes that it is helpful guidance for this and future PRs, so there is more feedback than i likely would normally offer.

[estelle]

The rest of the feedback.

I created a few codepens to help me understand. They're at
https://codepen.io/estelle/pen/NPrQxzG
https://codepen.io/estelle/pen/MYeNKXp
https://codepen.io/estelle/pen/OPXKWao
https://codepen.io/estelle/pen/PwGYaor

[yisibl]

Please note that in some rules, random() is disabled, and I would like the documentation to reflect this.
w3c/csswg-drafts#10982

[estelle]

more feedback. Also see https://github.com/jdatapple/content/pulls

[estelle]

just a few tweaks and we'll be good to go.

(Note: i committed some of the lintbot's suggestions so i could more easily read the page)

[estelle]

Suggested change

	- : A random base value is shared across all elements for a property using `random()` with this key term, while other properties on the same element using `random()` get a unique random base value.
	- : 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.

[estelle]

it can also be a combo, so "either" isn't right, unles we add <dashed-ident> element-shared as a option in the DL, so maybe:

Suggested change

	This can be either:
	This can be one of the following values, or both a custom key and the keyterm `element-shared`, separated by a space:

[estelle]

Suggested change

	The `random(SEED, MIN, MAX, STEP)` function specifies a minimum value and a maximum value, 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 `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.

[estelle]

Suggested change

The minimum, maximum and step values specified must be of the same {{cssxref("number")}}, {{cssxref("dimension")}}, or {{cssxref("percentage")}} 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("length")}}, {{cssxref("angle")}}, {{cssxref("time")}}, or {{cssxref("frequency")}} to be valid.

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.

[estelle]

Suggested change

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>`.

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.

[estelle]

Suggested change

Because `random()` can generate an unknown value within a range, you don't have full control over what you get and that can lead to inaccessible results. For example, if you use `random()` to generate color for text, you could end up with a value that has low contrast. So it's important to be mindful of the context in which `random()` is being used so that your results are still accessible.

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.

[estelle]

Suggested change

	In this example, we'll generate random colors for circular badge, to demonstrate the basic usage of the `random()` function.
	In this example, we'll generate random colors for some circular badges to demonstrate the basic usage of the `random()` function.

[estelle]

Suggested change

	We include five badges, one using the `desaturated` class, two with the `unique` class.
	We include five badges, one using the `desaturated` class and two using the `unique` class.

[estelle]

Suggested change

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 has the same {{cssxref("hue")}}, but with reduced saturation. We then override set the `unique` badges to have a truly random `hue` by letting the base value sharing parameter default to `auto`.

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`.

[estelle]

Suggested change

	- {{cssxref("calc()")}}
	- [CSS units and values](/en-US/docs/Web/CSS/Guides/Values_and_units) module
	- {{domxref("Math.random()")}}

order in css section is CSS reference first, then CSS module, then non-CSS section MDN references, then external links

[nt1m]

crossorigin/referrerpolicy are supported by safari 26.2

[estelle]

I am not sure of the syntax, so tested two ways in https://codepen.io/estelle/pen/MYjjRPJ. Both lines with referrer- policy() are listed as unsupported.

If supported, we need to get this into BCD and then document it.

(it's listed on https://webkit.org/blog/17640/webkit-features-for-safari-26-2, but without examples, and there is no mention in the CSS section under bug fixes and more)

[estelle]

Mike rebased, and I pressed "update branch", so your local copy and the remote branch are no longer synced. Before working locally:

1. commit any suggestions you want. The fasted way to do that is to go to https://github.com/mdn/content/pull/43161/files, and under any suggestion you want to add select "add to batch". Once done, at the top of the page select the "commit suggestions (n)" button. then the "commit changes" in the UI popup. You can also make changes in the github GUI and then commit them directly to the remote branch in this way.

2. Update the remote branch by hitting the "Update branch" button at the bottom of CSS random() reference doc #43161. This will ensure that all files on the branch are up to date with main.

3. Update your branch locally to match the remote branch you just updated. At the command line, enter git pull origin draft/css-random

4. Edit away locally!