Breakpoints: desktop-first or mobile-first

What this does

Every style you set in the editor, on an element, a global class or a theme style, is stored under the key of the breakpoint that was active when you set it. When a page is published, the compiler turns each key into a block of CSS. The base breakpoint's values are written as plain rules that apply at every width. A breakpoint narrower than the base gets @media (max-width:widthpx); one wider than the base gets @media (min-width:width of the next narrower one + 1px). Desktop-first means the widest breakpoint is the base, mobile-first means the narrowest is, and a base in the middle inherits both ways.

Breakpoints are design data of the global styles, edited in the editor's breakpoint manager. Settings → Builder → Breakpoints in WordPress only shows a read-only summary with a link to the manager.

The default breakpoints

A width is the upper end of the breakpoint's range: Tablet portrait covers 768 to 991 px. The widest breakpoint has no upper end, so its width only sets its canvas width in the editor.

Steps

1. Open the breakpoint manager.

   In the editor's top bar, click the button after the breakpoint icons (tooltip "Breakpoint manager"). The same manager is in Site settings → Breakpoints, and Open breakpoint manager under Settings → Builder opens the editor on it. Changing breakpoints needs the edit_theme_options capability; without it the manager says "You cannot change breakpoints (edit_theme_options required)".

2. Change a width or a label.

   Type into the Width column: a whole number from 120 to 4000 that no other breakpoint uses. Canvas sets the width the canvas shows for that breakpoint; empty means the breakpoint width. The canvas follows at once.

3. Add a breakpoint.

   Click Add breakpoint, enter a label (for example "Large desktop") and a width, and click Add. The new row gets the badge "Custom" and the key bp_ plus the width, for example bp_1440; if that key is taken, a letter is appended.

4. Pause or delete one.

   The On toggle pauses a breakpoint: it keeps its values but produces no CSS. The four default breakpoints can only be paused or reset ("Default breakpoints can be paused, not deleted"); custom ones also have Delete breakpoint. The base cannot be paused, and at least one breakpoint must stay enabled.

5. Choose the base.

   Click the radio in the Base column of another breakpoint. The dialog "Make “Mobile portrait” the base breakpoint?" explains the new direction; confirm with Set as base. Choosing the narrowest one makes the site mobile-first.

6. Save, then publish the global styles.

   Click Save breakpoints, or press Ctrl+S: until then the manager shows "Unsaved changes — saved together with the draft (Ctrl+S)". Visitors get the change when the global styles are published, with Publish globals in Site settings or together with your next page publish. That recompiles every published page into one new release (see Releases).

Why keys never change

A key is created once, from the width the breakpoint had when you added it, and stays when you later edit the width or the label. Styles are stored per key, optionally with a state such as bp_767:hover. A real example from the Studio starter site, a two-column grid that becomes one column on Tablet portrait and below:

"style": {
  "base":   { "display": "grid", "gridTemplateColumns": "1.1fr 0.9fr" },
  "bp_991": { "gridTemplateColumns": "1fr" }
}

Move Tablet portrait to 1023 px and the same value now applies up to 1023 px; nothing in any document is rewritten. Three consequences follow:

• The key base belongs to Desktop, not to whichever breakpoint is the base. After switching to mobile-first, values stored on Desktop stay on Desktop and apply from 992 px up ("Existing values do not move").
• Deleting a custom breakpoint leaves its values in documents and classes without CSS. Adding a breakpoint with the same key later brings them back.
• Reset all restores the four defaults, desktop-first; values of removed custom breakpoints stay stored but produce no CSS.

What you should see

• Managera badge "Desktop first", "Mobile first" or "Middle base" with one sentence on how the breakpoints inherit
• Each rowits range in px and the badges "Base", "Custom" or "Paused"
• Settings → Builderevery breakpoint with its range ("992 px and wider", "768 – 991 px", "Up to 478 px"), its key and the direction
• Published CSSbase values without @media, the others in one block per breakpoint

Limits

• One set of breakpoints per site; a page cannot have its own.
• Labels are required (up to 40 characters); keys are base or bp_ followed by 2 to 12 lowercase letters or digits.
• Switching the base never converts stored values. Review your pages after switching.
• Hiding an element on a breakpoint is CSS (display:none) on that exact range; the element stays in the HTML.
• Starter-site imports and "Set up starter styles" keep your breakpoints.

If it doesn't work

• "Another breakpoint already has this width". Two breakpoints cannot share a width; pick another.
• "Width must be a whole number from 120 to 4000". No units and no decimals.
• The canvas shows the change, the live site does not. The global styles are not published yet; Site settings shows "Globals draft not published".
• The layout broke after switching to mobile-first. Values on base now apply only from 992 px; the narrowest breakpoint's values apply everywhere. Move the values, or set Desktop as the base again.

Last verified 2026-10-20 · tested with DJIA Builder 1.0.20.15
To confirm Verified against the plugin code; run the steps on a test site before launch