Register custom breakpoints | Documentation

Overview

When working in an experience, you can change your design based on your user’s screen width. With breakpoints, we define at what screen width a user sees a different design. In Experiences, there are the following default breakpoints:

Breakpoint name	Screen width
`All Sizes`	Any
`Tablet`	Less than 992px
`Mobile`	Less than 576px

However, if the default breakpoints do not cover your needs, you can register custom breakpoints.

Create custom breakpoints

Breakpoint object

A breakpoint definition consists of the following properties:

Property	Value type	Description	Required
`id`	String	Must be a unique value.	Yes
`query`	String	Defines the range of viewport sizes that are targeted by this breakpoint using either `<` or `>`. The first breakpoint must have a wild card query.	Yes
`previewSize`	String	Defines the size of the canvas in the experience editor to test the view for this breakpoint. Make sure that this value is covered by the `query`.	Yes
`displayName`	String	Is displayed as a breakpoint label in the experience editor.	Yes
`displayIcon`	String	Possible values: `desktop`, `tablet`, `mobile`. We plan to support more breakpoint display icons in the future.	No

Update an experience with a custom breakpoint

We strongly recommend using only one set of breakpoint definitions within one space to avoid unexpected behavior. As the configuration will be copied into every single experience and pattern, please ensure that you remove or migrate all existing ones when making a change to your breakpoint definitions.

To add a custom breakpoint and update your experience to it:

To set up custom breakpoints, use the defineBreakpoints function and provide an array of breakpoint objects. The first breakpoint covers all sizes and must include a wildcard query (*). Breakpoints must follow either a desktop-first or mobile-first strategy, so list them either from largest to smallest pixel value or vice versa.

Example using a desktop-first strategy

1 import { defineBreakpoints } from '@contentful/experiences-sdk-react';
2 
3 defineBreakpoints([
4   {
5     id: 'desktop',
6     query: '*',
7     displayName: 'All Sizes',
8     displayIcon: 'desktop',
9     previewSize: '100%',
10   },
11   {
12     id: 'tablet',
13     query: '<992px',
14     displayName: 'Tablet',
15     displayIcon: 'tablet',
16     previewSize: '820px',
17   },
18   {
19     id: 'mobile',
20     query: '<576px',
21     displayName: 'Mobile',
22     displayIcon: 'mobile',
23     previewSize: '390px',
24   },
25 ])

Example using a mobile-first strategy

1 import { defineBreakpoints } from '@contentful/experiences-sdk-react';
2 
3 defineBreakpoints([
4   {
5     id: 'mobile',
6     query: '*',
7     displayName: 'All Sizes',
8     displayIcon: 'mobile',
9     previewSize: '390px',
10   },
11   {
12     id: 'tablet',
13     query: '>576px',
14     displayName: 'Tablet',
15     displayIcon: 'tablet',
16     previewSize: '820px',
17   },
18   {
19     id: 'desktop',
20     query: '>992px',
21     displayName: 'Desktop',
22     displayIcon: 'desktop',
23     previewSize: '100%',
24   },
25 ])

For an existing experience: update your experience with a custom breakpoint. To apply the custom breakpoint to your existing experience, de-select all the components in the canvas, then go to the Design tab of the right sidebar and click Update breakpoints.

Experiences update breakpoints

For newly created experiences, the updated breakpoints apply automatically.