CSS @contents At-Rule
The @contents at-rule marks where a block of CSS declarations passed to a mixin should be inserted. It works with @mixin and @apply, allowing reusable CSS rules to accept additional styles from the place where they are applied.
@contents Syntax
@contents;The @contents rule identifies the insertion point for declarations passed through an @apply block.
It can also contain a declaration block with fallback styles.
@contents {
color: #333;
}Both forms are defined in the CSS Custom Functions and Mixins specification.
How @contents Works
A CSS mixin defines reusable styling instructions. The @apply rule invokes the mixin, while @contents identifies where additional declarations supplied by the caller belong.
This allows a mixin to provide a common structure without requiring every element to use exactly the same declarations.
For example, a mixin can establish shared padding and borders while accepting different colors from each rule that uses it.
Passing Content to a Mixin
The following example defines a reusable card mixin. The @contents rule marks where the caller's additional declarations are inserted.
@mixin --card {
padding: 16px;
border: 1px solid #ccc;
@contents;
}
.card-blue {
@apply --card {
background-color: #e3f2fd;
}
}
.card-grey {
@apply --card {
background-color: #f5f5f5;
}
}Both cards receive the padding and border defined by the mixin. The declarations passed through their @apply blocks provide different background colors.
The mixin can be reused without repeating the shared declarations in every CSS rule.
Fallback Content
The block form of @contents allows a mixin to define fallback declarations for situations where no contents block is supplied.
@mixin --notice {
padding: 12px;
border: 1px solid #ccc;
@contents {
background-color: #f5f5f5;
}
}
.notice-default {
@apply --notice;
}
.notice-custom {
@apply --notice {
background-color: #fff3cd;
}
}The .notice-default rule uses the fallback background color. The .notice-custom rule supplies its own background color through the contents block.
This makes it possible to provide a default appearance while allowing individual uses of the mixin to customize the result.
@contents Example
The following example combines shared declarations, a fallback background color, and a custom contents block.
@mixin --panel {
padding: 15px;
border: 2px solid #555;
@contents {
background-color: #eee;
}
}
.panel-one {
@apply --panel;
}
.panel-two {
@apply --panel {
background-color: #d6eaff;
color: #123456;
}
}The first panel uses the mixin's fallback background. The second supplies its own background and text colors while retaining the shared padding and border.
Browser Support
The @contents at-rule is experimental and is not a widely supported browser feature. Browsers without support for CSS mixins ignore these rules, so production stylesheets should provide ordinary CSS fallbacks. Visit Can I Use? and search for CSS mixins to check for updates.
Specifications
The @contents at-rule is defined in the CSS Custom Functions and Mixins Module Level 1 draft specification. Its syntax and behavior may change as the specification develops.