CSS Linked Parameters Module Level 1

1. Introduction

SVG is stylable with CSS, and when used inline in HTML, this capability can be very useful. For example, an SVG icon can take on a different color based on whether the user is hovering it or not, just by applying a :hover rule to it that changes the fill property.

When the SVG is referenced in a way that doesn’t allow selectors or CSS inheritance from the outer page to apply to it (such as embedding it via img or iframe in HTML), though, this functionality is lost. The only way to change the display of such "external" SVG images is to produce several of them, and change which image you’re referencing. This incurs delay on the page as a new resource is downloaded, and disallows dynamic effects like CSS Transitions.

CSS link parameters are a way to set CSS custom environment variables on an "external" resource, either by a CSS property or thru a special fragment scheme on the URL. This gives a limited, but powerful, subset of the customizability that "inline" SVG images have to "external" SVG images, or to other linked resources that use CSS to style themselves.

A link parameter is a pair of a <dashed-ident> name, and an arbitrary (possibly empty) <declaration-value> value.

For example, an SVG image can be written to use link parameters, allowing it to have its colors changed on the fly, like:

<svg>
  <path fill="env(--color, black)" d="..." />
</svg>

By default, it will fill its shape with black, as that’s the fallback color specified. But link parameters can customize the color in several ways:

<img src="image.svg#:~:param(--color,green)">

img {
  link-parameters: param(--color, green);
}

.foo {
  background-image: url("image.svg", param(--color, green));
}

2. Setting a Link Parameter

An external resource can be accompanied by a list of link parameters, a struct composed of:

a name, usually a <dashed-ident>
an optional type, a <css-type>
a value (potentially empty), a CSS value

There are three ways to specify a link parameter:

via the link-parameters property, which applies to the resource itself (if the element represents an external resource), and to all external resources used in CSS properties on the element
via a fragment directive directly in the URL of an external resource.
via a param() argument in a <url>

If specified in multiple of these ways, all of the link parameters are appended into a single list for the external resource, in the order:

the link-parameters property on the element, if relevant
the link parameter directives of the URL
the param() <url-modifier>s in url()

If multiple link parameters exist with the same name, the last one in the list is used.

How to access link parameters in the linked resource is defined in the next section, § 3 Using Link Parameters.

2.1. The param() Function

All three methods of setting link parameters share the same syntax for defining a parameter, using the param() function:

param() = param( <param-spec> , <declaration-value>? )
<param-spec> = color | accent-color | [ <dashed-ident> <css-type>? ]

Depending on the <param-spec>, the param() function defines a link parameter in slightly different ways:

color

Name: color
Type: <color>
Value: The second argument, if specified. Otherwise, the value of color on the element.

accent-color

Name: accent-color
Type: <color>
Value: The second argument, if specified. Otherwise, the value of accent-color on the element.

<dashed-ident>

Name: the <dashed-ident>
Type: the <css-type>, if specified.
Value: The second argument, if specified. Otherwise, the value of the custom property with the specified name on the element.

Note that a completely empty second argument is valid, and is indicated by specifying the comma separating it from the first argument.

That is, param(--foo) indicates that the link parameter is using the default value, drawing from the --foo custom property on the element.

On the other hand, param(--foo,) explicitly gives the link parameter an empty value.

This is similar to var(--foo) having no fallback, but var(--foo,) having an empty fallback.

If the link parameter has a type, the value (default or manually provided) is parsed as that type. If it fails to parse as the given type, the link parameter is invalid and ignored. (The param() defining it is not invalid.)

Note: Authors can specify fallbacks by repeating a single param() multiple times, like param(--foo <color>, blue), param(--foo <color>, xztheta(1 2 3)), which will use the (currently undefined) xztheta() color function if it’s supported and blue in user agents that don’t support that function, similar to specifying a property multiple times.

A param() function usually has an element context from the way it’s used. If present, the value uses that context (and the type, if present) to fully resolve itself to a used value before being passed into the linked resource. If the value needs an element context to fully resolve, but doesn’t have one, the link parameter is invalid and ignored.

For example, param(--foo <color>, currentcolor) will use the element context to resolve to a specific color, rather than somewhat uselessly passing as the keyword.

Even without a type, arbitrary substitution functions will attempt to resolve in the value, and might need an element context (for example, var() and attr() both do).

Other values will be left unresolved without a type; for example, param(--foo, currentcolor) will pass the currentcolor keyword itself, without resolving it as a <color>, and thus doesn’t need an element context.

Similarly, if a param() doesn’t provide a second argument, and doesn’t have an element context, the link parameter is invalid and ignored. (Because the default draws on the value of a property on the element.)

2.2. For An Entire Element: the link-parameters property

Name:	link-parameters
Value:	none \| <param()>#
Initial:	none
Applies to:	all elements and pseudo-elements
Inherited:	no
Percentages:	n/a
Computed value:	as specified
Canonical order:	per grammar
Animation type:	discrete

The link-parameters property is one way to set link parameters on the element itself (if it is an element representing an external resource, such as an HTML img or iframe), and on all external CSS resources specified on the element (such as background images, etc). Its values are:

none: No link parameters are specified.
<param()>#: A list of one or more link parameters.

The param() functions used in link-parameters use the element they’re set on as the element context.

Note: If there are multiple images on the given element (content image and/or CSS images like backgrounds), they’ll all recieve all the values in link-parameters, even if they don’t use them. This is generally safe, as you need to use env() to access a link parameter in the linked resource, tho color and accent-color do have additional side-effects.

2.3. For A Single URL: the <url-modifier>

While link-parameters sets link parameters for every URL on an element, sometimes you want to set parameters for only one resource, or use the same resource multiple times on an element with different parameters. For this, you can use one or more param() functions directly in the <url> specifying the linked resource, as a <url-modifier>.

For example, if the site is using a --primary-color custom property to theme its elements with, and wanted an SVG background using env(--color) to reflect it, it could write:

.foo {
  background-image: url(
    "http://example.com/image.svg"
    param(--color, var(--primary-color))
  );
}

The param() functions used in a <url> use the element they’re set on as the element context.

2.4. Outside Of CSS: in the URL itself

Link parameters can be used outside of CSS, by embedding them directly into the URL as a fragment directive.

Note: Text directives are another example of fragment directives, letting you link to specific text somewhere in a document.

The link parameter directive is a fragment directive with the following syntax:

:~:param(...)

Where the ... represents any sequence of URL codepoints and/or percent-encoded bytes.

After URL-decoding, the link parameter directive is then parsed as a <param()>. If it fails to parse, the directive is ignored. Otherwise, it’s added to the embedded document’s list of link parameters, as specified in § 2.1 The param() Function.

For example, to set the env(--text-color) custom environment variable of an SVG image to blue, one can reference the image with a url like “http://example.com/image.svg#:~:param(--text-color,blue)”.

Note: Spaces, and some other characters that might be valid in CSS syntax, are not technically valid in URLs. In some contexts, you might need to escape those characters to form a valid URL. In most cases, though, such as HTML’s a element or CSS’s url() function, spaces are accepted and do not need to be escaped.

Multiple link parameters can be passed to an image by appending multiple link parameter directives to the URL. When combined, either with each other or with other "fragment identifiers", each value is separated with an & character, as in a URL’s query parameters.

For example, if the image from the previous example also used env(--bg-color), it could be referenced with a url like “http://example.com/image.svg#:~:param(--text-color,blue)&param(--bg-color,white)” to set both env(--text-color) and env(--bg-color).

If the URL is specified in a URL attribute on an element, such as <img src="...">, resolving the param() values (as specified in § 2.1 The param() Function) uses that element as the context. Otherwise (for example, if navigated to directly in the URL bar) there is no element context.

For example, param(color) requires an element context (to obtain the default value, taken from the color property).

Using <img src="example.svg#:~:param(color)"> in your document works as expected, drawing from the img element’s color property. Navigating directly to example.svg#:~:param(color) will instead ignore the param(color), as if it weren’t passed at all.

Similarly, param(color, light-dark(black, white)) requires an element context (to determine the color scheme), and would work the same as above.

On the other hand, param(--foo, light-dark(black, white)) does not require an element context, as the parameter is untyped. The literal value light-dark(black, white) will be passed down to the linked resource, without resolving in any way, whether specified in <img src> or directly navigated to.

3. Using Link Parameters

When an external resource link has one or more link parameters specified, if the linked resource understands CSS (such as an SVG or HTML document), then those link parameters affect the style of the linked resource in certain ways, depending on the parameter’s name:

color: The initial value of the color property on the linked resource is set to the value.
accent-color: The initial value of the accent-color property on the linked resource is set to the value.
<dashed-ident>: A custom environment variable is established on the linked resource, using the name and value.

For example, if an SVG image wanted to expose a --color parameter, it could use it like:

<svg>
  <g style="fill: env(--color);">
    <path d="..." />
  </g>
</svg>

Alternately, it could just rely on the currentcolor keyword, allowing the color to be passed with param(color, blue).

It’s usually a good idea to make your SVG image usable even if no parameters are given, by providing "default values" for each of the custom properties. There are several ways to do this.

On each env() function, provide a fallback value, like fill: env(--color, blue).
If the env() is going to be used a lot, such that providing a fallback for each individual env() is troublesome, store the custom environment variable in a custom property on the root element with the default specified, like:
```
:root {
  --color: env(--color, blue);
}
```
In this example, if --color is provided via a linked parameter, var(--color) will contain its value. If not, it will contain the default blue value. In either case, var(--color) can be used in the stylesheet unconditionally, secure in the knowledge that it will always have a value.

Is it useful to supply the "color" and "accent-color" values via an environment variable as well? This would probably just mean defining env(color)/etc on all documents, resolving to the initial value of color.

3.1. Tainting

A custom environment variable created by a link parameter is attr()-tainted if the param() that defined the link parameter was attr()-tainted.

3.2. Multiple Images With The Same URL

When an HTML document contains multiple img elements with the same src value, it considers them all "the same image" in some respects. Notably, animation timers (animating a GIF or similar animated raster format, or driving a CSS animation on an SVG) are defined to match across all such elements, even if they’re added to the document at different times.

User agents generally implement this by creating only a single image document, shared by all the img elements. This solves the animation problem, and avoids wastefully creating duplicate documents when a single image is repeated many times on a page (such as in the infamous "Hamster Dance" website).

However, link parameters allow these separate images to be styled differently. (As does color-scheme, which affects the image’s preferred color scheme, and potentially the width/height of the img, which would affect the width/height media features.)

User agents must paint images with the correct styling values in these cases. To the extent that it’s unobservable, they can still use a shared document; for example, they can associate each img with its own bespoke list of painting commands or cached rasterization while still having them share an underlying SVG document.

Privacy Considerations

This specification introduces no new privacy considerations.

Security Considerations

This specification introduces a new way to pass information to a linked resource, potentially from a hostile source.

While no explicit handshake is established for this channel, the use of env() to use the information minimizes the chance that the linked resource can be surprised by the information. The only way for the page to be vulnerable is to somehow be using an unknown env() in their styles, which will just result in invalid properties by default, and be visible in the developer’s Dev Tools.

Any hostile information can also only affect individual CSS properties that the resource explicitly opts itself into.

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Advisements are normative sections styled to evoke special attention and are set apart from other normative text with <strong class="advisement">, like this: UAs MUST provide an accessible alternative.

Conformance classes

A style sheet is conformant to this specification if all of its statements that use syntax defined in this module are valid according to the generic CSS grammar and the individual grammars of each feature defined in this module.

A renderer is conformant to this specification if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by this specification by parsing them correctly and rendering the document accordingly. However, the inability of a UA to correctly render a document due to limitations of the device does not make the UA non-conformant. (For example, a UA is not required to render color on a monochrome monitor.)

An authoring tool is conformant to this specification if it writes style sheets that are syntactically correct according to the generic CSS grammar and the individual grammars of each feature in this module, and meet all other conformance requirements of style sheets as described in this module.

Partial implementations

So that authors can exploit the forward-compatible parsing rules to assign fallback values, CSS renderers must treat as invalid (and ignore as appropriate) any at-rules, properties, property values, keywords, and other syntactic constructs for which they have no usable level of support. In particular, user agents must not selectively ignore unsupported component values and honor supported values in a single multi-value property declaration: if any value is considered invalid (as unsupported values must be), CSS requires that the entire declaration be ignored.

Implementations of Unstable and Proprietary Features

Non-experimental implementations

Once a specification reaches the Candidate Recommendation stage, non-experimental implementations are possible, and implementors should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec.

To establish and maintain the interoperability of CSS across implementations, the CSS Working Group requests that non-experimental CSS renderers submit an implementation report (and, if necessary, the testcases used for that implementation report) to the W3C before releasing an unprefixed implementation of any CSS features. Testcases submitted to W3C are subject to review and correction by the CSS Working Group.

CSS Linked Parameters Module Level 1

Abstract

Status of this document