attr()

The attr() function's syntax is as follows:

attr( ? , ?)

The parameters are:

The attribute name whose value should be retrieved from the selected HTML element(s).

Specifies how the attribute value is parsed into a CSS value. This can be the raw-string keyword, a type() function, or a CSS dimension unit (specified using an identifier). When omitted, it defaults to raw-string.

• The raw-string keyword causes the attribute's literal value to be treated as the value of a CSS string, with no CSS parsing performed (including CSS escapes, whitespace removal, comments, etc). The is only used if the attribute is omitted; specifying an empty value doesn't trigger the fallback.

  css

  attr(data-name raw-string, "stranger")
  

  Note: This keyword was originally named and supported in Chromium browsers as string. Both keywords will be supported briefly, for backwards compatibility purposes.

• The type() function takes a as its argument that specifies what data type to parse the value into. The can be , , , , , , , , , , , , , or a combination thereof.

  css

  attr(id type(), none)
  attr(data-count type(), 0)
  

  To accept multiple types, list all allowed es in the type() function, separated by a |.

  css

  attr(data-size type( | ), 0px)
  

  Note: For security reasons is not allowed as a .

  To accept any data type, use * as the type. This still triggers CSS parsing but with no requirements placed on it beyond that it parses validly and substitutes the result of that parsing directly as tokens, rather than as a value.

  css

  attr(data-content type(*))
  

• The identifier specifies the unit a numeric value should have (if any). It can be the % character (percentage) or a CSS distance unit such as px, rem, deg, s, etc.

  css

  attr(data-size rem)
  attr(data-width px, inherit)
  attr(data-rotation deg)
  

The value to be used if the specified attribute is missing or contains an invalid value.

The return value of attr() is the value of the HTML attribute whose name is parsed as the given or parsed as a CSS string.

When an is set, attr() will try to parse the attribute into that specified and return it. If the attribute cannot be parsed into the given , the will be returned instead. When no is set, the attribute will be parsed into a CSS string.

If no is set, the return value will default to an empty string when no is set or the guaranteed-invalid value when an is set.

The attr() function can reference attributes that were never intended by the page author to be used for styling and might contain sensitive information (for example, a security token used by scripts on the page). In general, this is fine, but it can become a security threat when used in URLs. Therefore, you can't use attr() to dynamically construct URLs.

help

span[data-icon] {
  background-image: url(attr(data-icon));
}

Values that use attr() get marked as attr()-tainted. Using an attr()-tainted value as or in a makes a declaration become "invalid at computed value time" or IACVT for short.

Generally speaking, the modern attr() syntax is backward-compatible because the old way of using it — without specifying an — behaves the same as before. Having attr(data-attr) in your code is the same as writing attr(data-attr type()) or the simpler attr(data-attr string)).

However, there are two edge cases where the modern attr() syntax behaves differently from the old syntax.

In the following snippet, browsers that don't support the modern attr() syntax will discard the second declaration because they cannot parse it. The result in those browsers is "Hello World".

div::before {
  content: attr(text) " World";
}
div::before {
  content: attr(text) 1px;
}

In browsers with support for the modern syntax, the output will be … nothing. Those browsers will successfully parse the second declaration, but because it is invalid content for the content property, the declaration becomes "invalid at computed value time" or IACVT for short.

To prevent this kind of situation, feature detection is recommended.

A second edge case is the following:

#parent {
  --x: attr(data-attr);
}
#child::before {
  content: var(--x);
}

Browsers without support for modern syntax display the text "foo". In browsers with modern attr() support there is no output.

This is because attr() — similar to custom properties that use the var() function — get substituted at computed value time. With the modern behavior, --x first tries to read the data-attr attribute from the #parent element, which results in an empty string because there is no such attribute on #parent. That empty string then gets inherited by the #child element, resulting in a content: ; declaration being set.

To prevent this sort of situation, don't pass inherited attr() values onto children unless you explicitly want to.

You can feature detect support for modern attr() syntax using the @supports at-rule. In the test, try to assign advanced attr() to a (non-custom) CSS property.

For example:

@supports (x: attr(x type(*))) {
  /* Browser has modern attr() support */
}

@supports not (x: attr(x type(*))) {
  /* Browser does not have modern attr() support */
}

We can perform the same check in JavaScript with CSS.supports():

if (CSS.supports("x: attr(x type(*))")) {
  /* Browser has modern attr() support */
}

if (!CSS.supports("x: attr(x type(*))")) {
  /* Browser does not have modern attr() support */
}

 = 
  attr(  ? , ? )  

 = 
  [ ? '|' ]?   

 = 
  type(  )  |
  raw-string        |
         

 = 
  '*'                                                 |
   [   ]*  |
                                       

 = 
   ?  |
  '<' transform-list '>'                          

 = 
  '|'  

 = 
    

 = 
  '<'  '>'  |
                       

 = 
  '#'  |
  '+'  

 = 
  angle               |
  color               |
  custom-ident        |
  image               |
  integer             |
  length              |
  length-percentage   |
  number              |
  percentage          |
  resolution          |
  string              |
  time                |
  url                 |
  transform-function  

In this example, we prepend the value of the data-foo data-* global attribute to the contents of the

element.

HTML

world

CSS

[data-foo]::before {
  content: attr(data-foo) " ";
}

Result

In this example, we append the value of data-browser data-* global attribute to the

element. If the data-browser attribute is missing from the

element, we append the fallback value of "Unknown".

HTML

My favorite browser is:
Your favorite browser is:

CSS

p::after {
  content: " " attr(data-browser, "Unknown");
  color: tomato;
}

Result

In this example, we set the CSS value of background-color to the value of the data-background data-* global attribute assigned to the

  background expected to be red if your browser does not support advanced usage
  of attr()

.background {
  height: 100vh;
}

.background {
  background-color: red;
}

.background[data-background] {
  background-color: attr(data-background type(), red);
}

In this example the data-rotation attribute is parsed into a deg unit, which specifies the element's rotation.

HTML

I am rotated by -3 degrees
And I by 2 degrees
And so am I, using the fallback value of 1.5deg

CSS

body {
  min-height: 100svh;
  display: grid;
  place-content: center;
  gap: 1em;
}
div {
  margin: 0 auto;
  border: 1px solid;
  border-radius: 0.25em;
  padding: 0.5em;
}

div {
  width: fit-content;
  transform-origin: 50% 50%;
  rotate: attr(data-rotation deg, 1.5deg);
}

Result

In this example, the values for the view-transition-name property are derived from the id attribute of the element. The attribute gets parsed into a , which is what view-transition-name accepts as a value.

The resulting values for view-transition-name are card-1, card-2, card-3, etc.

HTML

The HTML contains four cards with different id attributes and a "Shuffle cards" , which shuffles the cards.

html

  
1
  
2
  
3
  
4

Shuffle cards