@custom-media - CSS At-rule

@custom-media

Summary of characteristics of the @custom-media at-rule

Quick description
Defines the conditions of a custom media query.
Status
Compatibility issues ⚠
W3C Module
Media Queries
References (W3C)
Document status: WD (Working Draft)

Description of the @custom-media at-rule.

@custom-media sets the conditions for a media query, which can then be included in a @media at-rule. This helps avoid repeating the definition of a media query multiple times in the style-sheet. We know that repeating a definition leads to errors and makes maintaining style-sheets more complicated.

The example below defines the name --dinosaur and matches it to a series of conditions describing low-performing or old hardware: a monochrome or small-sized screen. This name can then be used in one or more @media directives.

@custom-media --dinosaur (monochrome), (width < 780px), (height < 600px); @media (--dinosaur) { ... }

The comma is equivalent to or, but it's possible to use this keyword instead. Similarly, the keywords and and not can be used.

If a custom media query is included in an expression with other conditions, the custom media query is evaluated first.

@custom-media --small-screen (width < 780px) or (height < 600px); @media (monochrome) and (--small-screen) { ... } /* is equivalent to */ @media ((width < 780px) or (height < 600px)) and (monochrome) { ... }

A custom media query can call other custom media queries. But be careful not to create loops. If a loop is detected by browsers, all the media queries that are part of the loop might become invalid.

If several custom media requests define the same name, only the last version is considered. Previous definitions are ignored.

The keywords true or false can be used in a custom media query (in this case, there’s no need to include other conditions). These keywords can be used to write a custom media query that is always true or always false, for debugging purposes, for example.

@custom-media --active true; @custom-media --inactive false;


The syntax for conditions is the same as that of @media. Check out the @media directive.

Browsers compatibility with the @custom-media at-rule..

The directive @custom-media is still poorly supported (2026). It can't be used. Only Firefox   handles it, and you still need to enable a flag (see how access flags on Firefox).

Column 1
Support for the @custom-media directive, which lets you define a custom @media-query rule.

Notes:

(1) Disabled by default. Can be enabled by setting the flag layout.css.custom-media.enabled to true.

1
@custom-media
at-rule
Estimated overall support.
1%

Browsers on computers :

Mobile browsers :

Outdated or marginal browsers :

Internet Explorer

UC Browser pour Androïd

Opéra Mobile

QQ Browser

Baidu Browser

Samsung Internet

Androïd Brower

Chrome

Chrome pour Androïd

Edge

Firefox

1

Firefox pour Androïd

KaiOS Browser

Opéra

Safari

Safari sur IOS

Opéra mini

See Caniuse.com for more compatibility information.
Caniuse

Evolution of the @custom-media at-rule.

  • Media Queries Level 5

    Level 5 introduces the ability to test a wide range of features, such as the number of screen segments, video characteristics, the presence of a scripting language, and more.
    Custom @media queries are also introduced.

    Regarding @custom-media First description of the @custom-media at-rule.
    WD
    March 03, 2020
    Working Draft.
    CR
    PR
    REC

See also, about media queries.

@custom-media is described in the specification "Media Queries". See also, in this same module:

At-rules:

@custom-media
Defines the conditions of a custom media query.
@media
Applying CSS rules based on device characteristics (screen size, presence of a mouse, etc.).