Working with Breakpoints in Drupal 8

Drupal 8 does not have a user interface for editing breakpoints. Because breakpoints are defined in configuration files, it's also not possible to provide a UI in contrib.

Breakpoints are used to segment the height or width of viewports (screens, printers, and other media output types) into stages, allowing responsive design to adapt for proper display across various devices. The Breakpoints module standardizes the use of breakpoints and allows modules and themes to expose or use each other's breakpoints. It tracks breakpoints by height, width, and resolution.

Note: Defining your CSS breakpoints in a breakpoints.yml file is only necessary when Drupal needs to interact with the breakpoints, such as with the Responsive Images module.

Terminology

Breakpoints

A breakpoint consists of a label and a media query. Media queries are a formal way of coding breakpoints. For example, a width breakpoint at 40em is written as the media query '(min-width: 40em)'. Breakpoints are simply media queries with additional metadata like name and multiplier information.

Themes and modules can define breakpoints by creating a configuration file named myThemeOrModule.breakpoints.yml, where myThemeOrModule is the name of your theme or module.

Each entry in this file defines one breakpoint with a machine name identifier (e.g., bartik.mobile) and the following properties:

• label - A human-readable label for the breakpoint.
• mediaQuery - The actual media query text, e.g., 'all and (min-width: 851px)'.
• weight - Positional weight (ordering) for the breakpoint.
• multipliers - Supported pixel density multipliers.

Note: The order of breakpoints by their weight is very important. Breakpoints with smaller minimum widths should have lower weights, and those with larger widths should have higher weights. Modules sort breakpoints from smallest to largest by default, but some like the Responsive Image module reverse this order based on weight.

Example (bartik.breakpoints.yml):

bartik.mobile:
  label: mobile
  mediaQuery: ''
  weight: 0
  multipliers:
    - 1x
bartik.narrow:
  label: narrow
  mediaQuery: 'all and (min-width: 560px) and (max-width: 850px)'
  weight: 1
  multipliers:
    - 1x
bartik.wide:
  label: wide
  mediaQuery: 'all and (min-width: 851px)'
  weight: 2
  multipliers:
    - 1x

Breakpoint Group

Breakpoints can be organized into groups. Modules and themes should use groups to separate breakpoints for different purposes, like layout or image sizing.

A breakpoint group is a set of breakpoints. Each theme or module can define zero or more groups. A group is defined using the breakpoint's identifier and a group key. If no group is specified, the default group name is the same as the theme or module.

For example, in yourtheme.breakpoints.yml you could define these two groups:

yourtheme.group1.mobile:
  label: narrow
  mediaQuery: ''
  weight: 0
  multipliers:
    - 1x
  group: yourtheme.group1
yourtheme.group1.narrow:
  label: narrow
  mediaQuery: '(min-width: 560px)'
  weight: 0
  multipliers:
    - 1x
    - 2x
  group: yourtheme.group1
yourtheme.group1.wide:
  label: wide
  mediaQuery: '(min-width: 851px)'
  weight: 1
  multipliers:
    - 1x
    - 2x
  group: yourtheme.group1

yourtheme.group2.mobile:
  label: narrow
  mediaQuery: ''
  weight: 0
  multipliers:
    - 1x
  group: yourtheme.group2
yourtheme.group2.narrower:
  label: narrow
  mediaQuery: '(min-width: 400px)'
  weight: 0
  multipliers:
    - 1x
    - 2x
  group: yourtheme.group2
yourtheme.group2.wider:
  label: wide
  mediaQuery: '(min-width: 1001px)'
  weight: 1
  multipliers:
    - 1x
    - 2x
  group: yourtheme.group2

Using the theme/module name, a dot, then the group name in both the breakpoint ID and group key ties breakpoints to the same group.

Currently, you cannot define a custom label for breakpoint groups; the machine name used in the group key will appear in UIs like Responsive Image configuration.

Advanced Usage

You can add breakpoints to groups defined by other modules or themes using the full identifier.

For example, in yourmodule.breakpoints.yml:

yourmodule.yourtheme.group2.superwide:
  label: superwide
  mediaQuery: '(min-width: 1501px)'
  weight: 1
  multipliers:
    - 1x
    - 2x
  group: yourtheme.group2

This adds a breakpoint defined in your module to a group in your theme.

Multipliers

Multipliers represent the device pixel ratio — the ratio between physical and device-independent pixels. For example, retina displays typically have a multiplier of 2x.

The Breakpoint module defines 1x, 1.5x, and 2x. You can declare which apply per breakpoint.

Example:

'1.5x' // supports Android
'2x'   // supports Mac retina display

Loading New Breakpoints Files

If you add a new breakpoints.yml file while testing, rebuild caches to make them visible to Drupal.

Resources

• Media Queries: W3C Recommendation, June 19, 2012
• Breakpoint-sass.com