> This page is for Studio.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://contentful-staging.ferndocs.com/developers/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful-staging.ferndocs.com/developers/docs/_mcp/server.

# Register custom breakpoints

> Learn how to register custom breakpoints for Experiences by Contentful Studio.

## 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

> **Info**
>
> 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:

1. Register a custom breakpoint.

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

```TypeScript
import { defineBreakpoints } from '@contentful/experiences-sdk-react';

defineBreakpoints([
  {
    id: 'desktop',
    query: '*',
    displayName: 'All Sizes',
    displayIcon: 'desktop',
    previewSize: '100%',
  },
  {
    id: 'tablet',
    query: '<992px',
    displayName: 'Tablet',
    displayIcon: 'tablet',
    previewSize: '820px',
  },
  {
    id: 'mobile',
    query: '<576px',
    displayName: 'Mobile',
    displayIcon: 'mobile',
    previewSize: '390px',
  },
])
```

#### Example using a mobile-first strategy

```TypeScript
import { defineBreakpoints } from '@contentful/experiences-sdk-react';

defineBreakpoints([
  {
    id: 'mobile',
    query: '*',
    displayName: 'All Sizes',
    displayIcon: 'mobile',
    previewSize: '390px',
  },
  {
    id: 'tablet',
    query: '>576px',
    displayName: 'Tablet',
    displayIcon: 'tablet',
    previewSize: '820px',
  },
  {
    id: 'desktop',
    query: '>992px',
    displayName: 'Desktop',
    displayIcon: 'desktop',
    previewSize: '100%',
  },
])
```

2. 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](/developers/docs/_fern-img/300b18fc6a50142bc5af072f67dabc2667cd2171812fb97c93cb1b8326e527ee.webp)

> **Info**
>
> For newly created experiences, the updated breakpoints apply automatically.