Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / CSS

supports(): a CSS condition with context-dependent support

Distinguish a conditional stylesheet import, the draft @when notation, the @supports rule and the JavaScript API.

Version: CSS Modules

Syntax

@import url("grid.css") supports(display: grid);

supports() is a CSS feature condition, not a property value or a JavaScript call. In @import, supports(display: grid) allows the imported stylesheet only when the declaration is supported. A full supports condition can also be used, including not or parenthesized combinations. The function follows the URL and optional layer clause, before any media query. Keep imports before ordinary style rules; a false supports condition prevents fetching and applying that imported sheet.

CSS Conditional Rules Level 5 also defines supports(declaration) inside the proposed @when rule. That context has separate implementation status. It must not be inferred from working @import conditions, the established @supports rule, or CSS.supports() in JavaScript. The latter accepts a property/value pair or a supports-condition string, not the supports(...) wrapper used in these CSS contexts. Conditional import syntax is defined separately in CSS Cascade.

The example uses local data stylesheets and reads a property they actually set. The supported grid import wins; the deliberately unsupported display value does not override it. In the tested Chromium 157, the @when block is omitted and the fallback remains. Its CSSOM exposes one import rule and no @when rule. The JavaScript declaration test returns true while the wrapped string returns false. These are explicit observations of distinct mechanisms, not a claim that all supports() contexts work.

A positive feature query means the browser reports support; it does not prove a particular page is bug-free, accessible or visually correct. Keep useful fallback styles and test the behavior you depend on. The local example verifies style application, not real network traffic, caching or the availability of a remote stylesheet.

Examples

const box=document.createElement('div');box.id='supports-probe';document.body.append(box);
const style=document.createElement('style');
const sheet=value=>'data:text/css,'+encodeURIComponent('#supports-probe { --imported: '+value+'; }');
style.textContent='@import url("'+sheet('grid')+'") supports(display: grid);\n@import url("'+sheet('invalid')+'") supports(display: definitely-not-a-display);\n#supports-probe { --when: fallback; }\n@when supports(display: grid) { #supports-probe { --when: matched; } }';
await new Promise((resolve,reject)=>{const timer=setTimeout(()=>reject(new Error('Stylesheet load timed out')),3000);style.onload=()=>{clearTimeout(timer);resolve()};style.onerror=()=>{clearTimeout(timer);reject(new Error('Stylesheet failed'))};document.head.append(style)});
const value=getComputedStyle(box);
console.log('imported='+value.getPropertyValue('--imported').trim()+'; when='+value.getPropertyValue('--when').trim());
console.log('imports='+[...style.sheet.cssRules].filter(rule=>rule.type===CSSRule.IMPORT_RULE).length+'; when-rules='+[...style.sheet.cssRules].filter(rule=>rule.cssText.startsWith('@when')).length);
console.log('js-declaration='+CSS.supports('display','grid')+'; js-wrapped='+CSS.supports('supports(display: grid)'));
style.remove();box.remove();

Result

imported=grid; when=fallback
imports=1; when-rules=0
js-declaration=true; js-wrapped=false

The data URLs contain only the tiny CSS fixtures shown in the code. @when remains a draft context and was not implemented by the tested Chromium 157; the working conditional import does not change that result.

Sources