Last updated August 27, 2015. Created on October 4, 2012.
Edited by kenisha.lehari, mdrummond, eojthebrave, mariohernandez. Log in to edit this page.

There is no user interface for editing breakpoints in Drupal 8. Due to the fact that breakpoints are config, it's not possible to provide a UI in contrib as well.

Warning: this documentation is outdated.

Breakpoints are used to separate the height or width of viewports (screens, printers, and other media output types) into steps and provide for the case where a responsive design adjusts in order to display correctly on different devices. The Breakpoints module standardizes the use of breakpoints, and enables modules and themes to expose or use each others' breakpoints. The Breakpoint module keeps track of the height, width, and resolution breakpoints.



A breakpoint consists of a label and a media query. Media queries are a formal way to encode breakpoints. For instance, a width breakpoint at 40em is written as the media query '(min-width: 40em)'. Breakpoints are really just media queries with some additional metadata, such as name and multiplier information.

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

Each entry in this file defines one breakpoint, consisting of a machine name, by which the breakpoint entry is uniquely identified e.g., and it's children defining the breakpoint's properties:

  • label - A human readable label for the breakpoint.
  • mediaQuery - Media query text proper ('all and (min-width: 851px)'.
  • weight - Positional weight (order) for the breakpoint.
  • multipliers - Supported pixel resolution multipliers.

Note: The order in which breakpoints are arranged through their weight value is extremely important. Breakpoints with the smallest min-width should have the lowest weight, while breakpoints with the largest min-width should have a larger weight value. By default, modules will order breakpoints from smallest to largest. However modules can reverse that order if necessary: for example the Responsive Image module takes care of re-ordering breakpoints from largest to smallest based on the weight value.

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

Breakpoint group

Breakpoints can be organized into groups. Modules and themes should use groups to separate out breakpoints that are meant to be used for different purposes, such as breakpoints for layouts or breakpoints for image sizing.

A breakpoint group is a combination of breakpoints. Each theme or module can define zero or more breakpoint groups using a file named myThemeOrModule.breakpoint_groups.yml. A breakpoint group that contains all defined breakpoints is created automatically for each theme or module.

Example (auto-created for Bartik theme):

     - theme.bartik.narrow
     - theme.bartik.wide
id: bartik
label: Bartik

To define your own breakpoint groups, use the following:

    label: Group 1
      - mobile
      - wide
  label: Group 2
     - mobile
     - wide
     - narrow

Advanced use

You can also add breakpoints defined by other modules or themes, but you must use the full name.

  label: Test Module
    - theme.breakpoint_test_theme.narrow
    - theme.breakpoint_test_theme.wide


Multipliers are a measure of the viewport's device resolution, defined as the ratio between the physical pixel size of the active device and the device-independent pixel size. e.g.) "retina" displays. The breakpoint module defines multipliers of 1x, 1.5x and 2x. When defining breakpoints, modules and themes can define which multipliers apply to each breakpoint.


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

Disable/re-enable the theme to load new breakpoint files

If you add a new breakpoints config file during theme testing, you must disable then re-enable the theme to have the new file loaded. A cache flush won't do it.


Looking for support? Visit the forums, or join #drupal-support in IRC.