CSS @custom-selector At-Rule
The @custom-selector at-rule defines a reusable name for a CSS selector or selector list. It allows complex or frequently used selectors to be written once and referenced in multiple CSS rules, making stylesheets easier to maintain.
@custom-selector Syntax
@custom-selector :--custom-name selector;The declaration begins with @custom-selector, followed by a custom pseudo-class name, a selector or selector list, and a semicolon.
The custom name begins with :-- and can be used in subsequent CSS selectors.
@custom-selector :--headings h1, h2, h3;
:--headings {
color: #333;
}The custom selector :--headings represents the three heading elements.
How @custom-selector Works
A custom selector acts as an alias for one or more existing CSS selectors. Instead of repeating a selector throughout a stylesheet, you define a name and reference it where needed.
@custom-selector :--buttons .btn-primary, .btn-secondary;
:--buttons {
padding: 10px 16px;
border-radius: 4px;
}
:--buttons:hover {
opacity: 0.85;
}The :--buttons selector represents both button classes. The shared styles and hover effect apply to elements matching either class.
Custom selectors do not create new HTML elements or classes. They provide reusable aliases for selectors already defined by CSS.
Selector Lists
A custom selector can represent multiple selectors separated by commas.
@custom-selector :--form-fields input, select, textarea;
:--form-fields {
border: 1px solid #aaa;
padding: 8px;
}The declaration groups three form controls under the name :--form-fields.
When the custom selector is referenced, it represents the selectors in its definition.
This can be useful when the same group of elements requires consistent styling across multiple rules.
Combining Selectors
Custom selectors can be combined with other selectors, pseudo-classes, and combinators to create more specific rules.
Using a Custom Selector with :hover
@custom-selector :--links a, .link;
:--links:hover {
text-decoration: underline;
}The rule targets matching links when they are hovered.
Using a Custom Selector with :is()
@custom-selector :--titles h1, h2, h3;
article :is(:--titles) {
margin-bottom: 12px;
}The :is() pseudo-class can group selector alternatives. In this example, the custom selector represents headings inside an article element.
The exact specificity of a custom selector depends on the selectors in its definition and the rules for custom selector expansion.
Browser Compatibility
The @custom-selector at-rule is experimental and does not have broad native browser support.
For production stylesheets, ordinary selector lists and the :is() pseudo-class are widely supported alternatives.
Standard CSS Alternative
h1, h2, h3 {
color: #333;
}This rule provides the same styling as the earlier heading example without requiring custom selector support.
CSS processing tools can also transform custom selectors into standard CSS before the stylesheet is delivered to browsers.
@custom-selector Example
The following example defines a reusable selector for highlighted content and applies shared formatting.
@custom-selector :--highlight .notice, .alert, .message;
:--highlight {
padding: 12px;
border: 1px solid #ccc;
background-color: #f5f5f5;
}
:--highlight strong {
color: #0056b3;
}The three classes share the same padding, border, and background color. Strongly emphasized text inside these elements receives a blue text color.
Because browser support is limited, this example is provided as code rather than a live preview.
Browser Support
The @custom-selector at-rule is not widely supported in modern browsers. Use standard selector lists or a CSS build tool when compatibility is required. Visit Can I Use? and search for CSS custom selectors for current compatibility information.
Specifications
The @custom-selector at-rule is described in the CSS Extensions specification draft. Its syntax and behavior may change as the feature develops.