Breakpoint

A Drupal breakpoint is a labeled screen condition defined in YAML, which responsive image styles use to pick the right image file for each screen.

Learn DrupalDrupal glossary
Edited by Founder and CEO, DXPR Last updated

A breakpoint is a named media query that marks a screen width, or another viewport condition, where a design should change. In Drupal, a theme or module registers breakpoints in a .breakpoints.yml file. The core Breakpoint module reads them, so features such as responsive images can react to the same widths.

How breakpoints work in Drupal 11

The BreakpointManager plugin manager discovers an EXTENSION_NAME.breakpoints.yml file in each module and theme. Every entry is keyed by a machine name and has four keys:

  • label: the human-readable name.
  • mediaQuery: the media query string.
  • weight: the order within the group.
  • multipliers: the resolutions that apply, such as 1x or 2x.

A group key is optional. Without it, the group is the name of the module or theme. The manager always adds the 1x multiplier and sorts the multipliers numerically.

The main consumer in core is the Responsive Image module, which depends on Breakpoint. A responsive image style chooses a breakpoint group and maps each breakpoint and multiplier to an image style. The output is either a picture element whose source tags carry each breakpoint's media query, so the browser picks the first source whose condition matches, or an img tag with srcset and sizes.

Example

Olivero registers eight breakpoints. Two of them look like this, in olivero.breakpoints.yml:

olivero.md:
          label: Medium
          mediaQuery: 'all and (min-width: 700px)'
          weight: 1
          multipliers:
            - 1x
        olivero.lg:
          label: Large
          mediaQuery: 'all and (min-width: 1000px)'
          weight: 2
          multipliers:
            - 1x

Neither entry names a group, so both belong to the group olivero. A responsive image style that uses that group can serve one image from 700 pixels wide and another from 1000 pixels.

Common mistakes

  • Expecting the YAML file to change the layout. It describes widths for Drupal features. Your stylesheet still needs its own media queries.
  • Getting the weights backwards. Order breakpoints from the smallest min-width upward, as the Drupal.org guide advises.
  • Skipping the cache rebuild. Rebuild caches after you add a file, as the Drupal.org guide says.
  • Mixing purposes in one group. The module's help topic recommends separate groups for layout breakpoints and image-sizing breakpoints.

For marketing and content teams

Breakpoints decide at which screen widths a responsive image switches to another file. If a hero image is too small or too heavy at some screen width, ask your developer to check the responsive image style's mapping for that breakpoint. Tell them which devices matter to your audience and which image crop you expect at each width. They translate that into breakpoints and image styles, which is the practical side of responsive design.

Sources

Questions about Breakpoint

No. The Breakpoint module only keeps track of the definitions, and its help text says it has no user interface. A breakpoint file does not replace the media queries in your stylesheets. Other modules, such as Responsive Image, read the definitions.

Create mytheme.breakpoints.yml in the theme's base directory. Each entry has a machine name, label, mediaQuery, weight and multipliers, and may add a group. Rebuild the caches afterwards so Drupal finds the new file.

It is a resolution multiplier: the ratio between the device's physical pixels and its device-independent pixels. The Breakpoint module defines 1, 1.5 and 2. When a definition omits 1x, the plugin manager adds it for you.

Nowhere; they live in YAML files. You meet them in Configuration › Media › Responsive image styles, where each style picks a breakpoint group and maps its breakpoints to image styles.

Related terms

All Drupal terms from A to Z