CSS @custom-media At-Rule

CSS @custom-media At-Rule

The @custom-media at-rule defines a reusable name for a media query condition. Instead of repeating the same condition throughout a stylesheet, you can declare it once and reference it in multiple @media rules.

@custom-media Syntax

@custom-media --small-screen (max-width: 600px);

The declaration consists of the @custom-media keyword, a custom name beginning with two hyphens, a media query condition, and a semicolon.

Unlike block-based at-rules, @custom-media does not use curly braces. Its name can be referenced in a media query using parentheses.

@media (--small-screen) {
  .container {
    padding: 10px;
  }
}

The media query matches when the condition associated with --small-screen is satisfied.

How @custom-media Works

Media queries apply CSS rules based on conditions such as viewport width, device orientation, and user preferences. The @custom-media at-rule gives a reusable name to one of these conditions.

For example, several parts of a stylesheet might need to respond to a viewport width of 768px or less.

@custom-media --tablet (max-width: 768px);
@media (--tablet) {
  .navigation {
    display: block;
  }
}
@media (--tablet) {
  .sidebar {
    display: none;
  }
}

Both @media rules reference the same named condition. If the breakpoint needs to change, the custom media declaration provides one place to update it.

Custom media queries do not create CSS custom properties. Although their names begin with two hyphens, they are media query definitions rather than values accessed with the var() function.

Naming Rules

Custom media names begin with two hyphens and use the CSS custom identifier syntax.

Descriptive names make media query conditions easier to recognize and maintain.

@custom-media --mobile (max-width: 480px);
@custom-media --tablet (min-width: 481px) and (max-width: 1024px);
@custom-media --dark-theme (prefers-color-scheme: dark);

The names --mobile, --tablet, and --dark-theme identify conditions that can be reused throughout a stylesheet.

Custom media names are case-sensitive. For example, --mobile and --Mobile are different names.

Combining Conditions

A custom media query can contain multiple conditions, including logical operators such as and, not, and comma-separated alternatives.

Combining Width and Orientation

@custom-media --compact-landscape (max-width: 900px) and (orientation: landscape);
@media (--compact-landscape) {
  .layout {
    gap: 10px;
  }
}

The rule applies when the viewport is no wider than 900px and its orientation is landscape.

Using Multiple Alternatives

@custom-media --reduced-effects (prefers-reduced-motion: reduce), (update: slow);
@media (--reduced-effects) {
  .animated-box {
    animation: none;
  }
}

This custom media query matches when the user prefers reduced motion or the device has a slow update frequency.

Named custom media conditions can also be combined with additional conditions inside an @media rule.

Browser Compatibility

The @custom-media at-rule is an experimental feature with limited native browser support. A browser that does not recognize a named custom media query will not apply the styles inside the affected @media rule.

For production websites, you can use ordinary media queries or a build tool that transforms custom media definitions into standard media queries.

Standard Media Query Alternative

@media (max-width: 600px) {
  .container {
    padding: 10px;
  }
}

This standard media query provides the same condition without requiring support for @custom-media.

Tools such as PostCSS can process custom media declarations during development and produce CSS that works in browsers without native support.

@custom-media Example

The following example defines a named breakpoint and uses it to adjust the layout of a page when the viewport becomes narrow.

@custom-media --narrow-screen (max-width: 600px);
.page-layout {
  display: grid;
  grid-template-columns: 2fr 1fr;
  gap: 20px;
}
@media (--narrow-screen) {
  .page-layout {
    grid-template-columns: 1fr;
    gap: 10px;
  }
}

In a browser that supports custom media queries, the layout changes from two columns to one when the viewport width is 600px or less.

Because native support is limited, the example is provided as code rather than a live browser preview.

Browser Support

The @custom-media at-rule is not widely supported across browsers. Standard @media queries remain the recommended approach when broad compatibility is required. Visit Can I Use? and search for CSS custom media queries for current compatibility information.

Specifications

The @custom-media at-rule is defined in the Media Queries Level 5 specification. It introduces named custom media queries for reusing media conditions.

Media Queries Level 5