Last updated April 15, 2015. Created on October 4, 2012.
Edited by eojthebrave, mariohernandez, alexrayu, benjy. 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.

Terminology

Breakpoint

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. bartik.mobile, 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. The browser will use the first breakpoint it can fulfill and ignore the rest even if the first breakpoint is not necessarily the correct one. When using "min-width" the recommendation is to arrange breakpoints from largest to smallest (desktop to mobile).

Example (bartik.breakpoints.yml):

bartik.mobile:
  label: mobile
  mediaQuery: ''
  weight: 2
  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: 0
  multipliers:
    - 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):

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

To define your own breakpoint groups, use the following:

group1:
    label: Group 1
    breakpoints:
      - mobile
      - wide
group2:
  label: Group 2
  breakpoints:
     - mobile
     - wide
     - narrow

Advanced use

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

moduletest:
  label: Test Module
  breakpoints:
    - theme.breakpoint_test_theme.mobile
    - theme.breakpoint_test_theme.narrow
    - theme.breakpoint_test_theme.wide

Multipliers

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.

Example:

'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.

Resources

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