Last updated November 22, 2014. Created on October 4, 2012.
Edited by benjy, sqndr, LoMo, iantresman. 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 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.

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 line in this file defines one breakpoint, consisting of a label (lowercase letters only) followed by a colon and a valid media query.

The order of the lines define the order of the breakpoints, which are ordered from the most narrow breakpoint to the widest breakpoint.

Example (bartik.breakpoints.yml):

mobile: '(min-width: 0px)'
narrow: 'all and (min-width: 560px) and (max-width: 850px)'
wide: 'all and (min-width: 851px)'

Breakpoint group

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 strings that support 'retina' displays, defined by a number (the multiplier) followed by an x. The breakpoint module defines 1x, 1.5x and 2x by default.


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

Module Uses

Defining breakpoints

Define breakpoints when layouts should shift from one form to another, when images should be resized, and other changes that need to occur when browser viewport height or width changes. 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.

The Breakpoint module can be used by themes and other modules to define breakpoints, which separate the height or width of viewports (screens, printers, and other media output types) into steps. For instance, a width breakpoint of 40em creates two steps: one for widths up to 40em and one for widths above 40em.

Assigning resolution multipliers to breakpoints

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. The Breakpoint module defines multipliers of 1, 1.5, and 2. When defining breakpoints, modules and themes can define which multipliers apply to each breakpoint.

Defining breakpoint groups

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.

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.