CSS Linked Parameters

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.

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

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

<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, each entry composed of a <dashed-ident> as a key, and a (possibly empty) <declaration-value> as the 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 special syntax in the fragment portion of the URL of an external resource

• via a param() argument in the url() syntax

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:

1. the link-parameters property on the element, if relevant

2. the param() URL fragment identifiers

3. 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. In CSS: the link-parameters property

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() function specifies a link parameter, with a key of the <dashed-ident>, and a value of the <declaration-value>?. (If the <declaration-value> is omitted, it represents an empty value.) It has the syntax:

<param()> = param( <dashed-ident> , <declaration-value>? )

2.2. In The URL

A special "fragment identifier" can be used in the fragment of a URL used to reference an external resource. Several examples of existing "fragment identifiers" for SVG documents can be found in the SVG 1.1 specification.

The syntax of an SVG parameter fragment identifier is:

param( <dashed-ident> , <declaration-value>? )

(using the CSS value definition syntax; TODO define an actual parser for it).

Multiple link parameters can be passed to an image by appending multiple param() fragment identifiers to the URL.

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.

2.3. Setting via the CSS url() Function

When referencing an external resource via CSS, the param() function can be used in the url() function. But a common use-case is passing in values of the page’s own custom properties; for example, a page might use a --primary-color custom property, and want to make an SVG image match. There’s no way, however, to integrate the value of a custom property in CSS into the URL passed to the url() function.

To accommodate this, param() is a valid <url-modifier>. All the param()s specified as a <url-modifier> define link parameters, as for link-parameters.

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

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 establish global custom environment variables for the resource with their name and value, accessible with the env() function in stylesheets.

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

Note: When we define env(parent --color) to jump up a scope level, you won’t need to do the rename; @env --color: env(parent --color); will work just fine.

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.