Custom Viewport Breakpoints in theme.json in 2026

Responsive controls are much more useful when their breakpoints match the website you are actually building.

A breakpoint that works for a simple blog may feel wrong for a wide navigation menu, a product grid, an agency landing page, or a content-heavy business site. Your header may start wrapping before WordPress switches to Tablet. A card grid may need to stack earlier. A hero heading may remain too large at widths where the layout already feels cramped.

WordPress 7.1 addresses this by letting block theme developers define custom viewport breakpoints inside theme.json.

Instead of accepting the default Mobile and Tablet widths for every project, a theme can define breakpoints that match its own design system. WordPress then uses those values for responsive block styling and viewport-based block visibility.

This guide explains how custom viewport breakpoints work, how to add them to theme.json, how inheritance behaves, what happens when values are invalid, and how to choose breakpoints without simply copying numbers from another framework.

{
```

"version": 3,
"settings": {
"viewport": {
"mobile": "600px",
"tablet": "960px"
}
}
}

What Are Viewport Breakpoints?

A viewport breakpoint is a width where a website changes how it presents content.

For example, at a certain width you may want to:

• Reduce heading size.
• Tighten section padding.
• Stack columns vertically.
• Hide a decorative image.
• Change an image’s aspect ratio.
• Reduce gaps between cards.
• Switch to a compact navigation layout.

The breakpoint does not represent one specific phone or tablet. It marks the point where the layout needs to behave differently.

This distinction matters. A good breakpoint is based on the content and design, not on trying to target every device model currently on the market.

Why Custom Breakpoints Matter in WordPress

Earlier WordPress responsive features relied on fixed viewport definitions. Those defaults worked as a general starting point, but themes could not align them with their own layout systems.

That created situations where:

• The editor called a layout Desktop even though the navigation was already wrapping.
• A theme’s custom CSS changed at one width while block visibility changed at another.
• Responsive block styles and a frontend design system did not share the same breakpoints.
• Theme developers had to work around hardcoded viewport assumptions.

Custom values in theme.json give the theme a central place to define its responsive viewport ranges.

The goal is not to create dozens of breakpoints. It is to give the theme one consistent definition of Mobile, Tablet, and Desktop.

Default WordPress Viewport Breakpoints

If a theme does not provide custom values, WordPress uses these defaults:

These values are reasonable defaults, but they will not suit every theme.

A theme with a large navigation menu may need Tablet to extend to 960px or 1024px. A minimalist blog may work perfectly with the defaults. A store with four-column product grids may need layout adjustments earlier than a text-focused site.

Where to Add Breakpoints in theme.json

Custom viewport values live inside the top-level settings object:

{
  "version": 3,
  "settings": {
    "viewport": {
      "mobile": "600px",
      "tablet": "960px"
    }
  }
}

The two supported values are:

• mobile: the maximum width for Mobile styles.
• tablet: the maximum width for Tablet styles.

You do not need to define a separate Desktop value. Desktop begins above the Tablet maximum.

A Complete theme.json Example

Here is a simplified block theme configuration with custom viewport breakpoints:

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {
    "layout": {
      "contentSize": "720px",
      "wideSize": "1200px"
    },
    "viewport": {
      "mobile": "600px",
      "tablet": "960px"
    },
    "spacing": {
      "padding": true,
      "margin": true,
      "blockGap": true
    },
    "typography": {
      "customFontSize": true,
      "lineHeight": true
    }
  }
}

The viewport configuration does not create responsive styles on its own. It defines the ranges WordPress should use when responsive styles or block-visibility rules are applied.

How the Three Viewport Ranges Are Calculated

Suppose your theme defines:

"viewport": {
  "mobile": "600px",
  "tablet": "960px"
}

WordPress interprets the ranges like this:

The names Mobile and Tablet are design labels. They should not be treated as a database of physical devices.

A narrow desktop browser can enter the Tablet range. A large tablet in landscape orientation may enter Desktop. That is normal. Responsive design reacts to available space, not the hardware name.

What Happens If You Define Only Mobile?

A theme can provide only one valid breakpoint:

{
  "version": 3,
  "settings": {
    "viewport": {
      "mobile": "640px"
    }
  }
}

In that case, WordPress keeps Mobile as a single maximum-width breakpoint.

The practical result is a simpler two-range system:

• Mobile at or below 640px.
• The wider base view above 640px.

This may be useful for a very simple theme, but most complete design systems will benefit from both Mobile and Tablet values.

What Happens If You Define Only Tablet?

You can also provide only a Tablet value:

{
  "version": 3,
  "settings": {
    "viewport": {
      "tablet": "900px"
    }
  }
}

The Tablet state then uses that value as its maximum width.

However, a two-breakpoint configuration is normally clearer because it gives responsive styling and visibility rules an explicit Mobile range as well.

Invalid Breakpoint Values

WordPress validates the viewport configuration. Invalid values are ignored.

For example, this configuration is logically wrong:

{
  "version": 3,
  "settings": {
    "viewport": {
      "mobile": "1000px",
      "tablet": "800px"
    }
  }
}

The Mobile maximum is greater than the Tablet maximum, so WordPress cannot create the expected Mobile-to-Tablet range.

Your values should always follow this relationship:

mobile < tablet

A valid configuration would be:

{
  "version": 3,
  "settings": {
    "viewport": {
      "mobile": "600px",
      "tablet": "900px"
    }
  }
}

If neither supplied value is valid, WordPress can fall back to its default breakpoints.

How Custom Breakpoints Affect Responsive Styling

WordPress 7.1 responsive styling lets editors give supported block styles different values for Desktop, Tablet, and Mobile.

For example, an editor may configure a Heading block with:

• 64px on Desktop.
• 48px on Tablet.
• 34px on Mobile.

Your theme.json breakpoints determine when those Tablet and Mobile values become active.

If Tablet ends at 960px rather than 782px, the Tablet heading style remains active through that wider range.

This lets the responsive editing experience reflect the theme’s actual design rather than forcing every project into the same fixed widths.

For the editor workflow, read Responsive Styling in WordPress 7.1 Without Custom CSS.

How Custom Breakpoints Affect Block Visibility

Viewport-based block visibility lets a user show or hide a block for selected viewport states.

For example, a theme might use:

• A detailed promotional image on Desktop.
• A simpler image on Tablet.
• No decorative image on Mobile.

The breakpoint values in theme.json decide when those visibility states apply.

This is useful because responsive styling and responsive visibility can now follow the same theme-level viewport definitions.

Use visibility responsibly. Hiding duplicated decoration is usually fine. Hiding essential product details, legal information, navigation, or conversion content can create accessibility and user-experience problems.

How to Choose the Right Breakpoints

Do not begin by asking, “What breakpoint does Bootstrap use?” or “What is the standard iPad width?”

Start with the layout.

1. Open the Widest Layout

View the page at full desktop width. Confirm that the normal design works properly.

2. Slowly Reduce the Width

Drag the browser or editor canvas narrower. Watch for the first point where the design stops feeling comfortable.

Look for:

• Navigation wrapping.
• Headings becoming awkward.
• Cards becoming too narrow.
• Buttons colliding.
• Images losing useful proportions.
• Columns becoming difficult to scan.

3. Record the Problem Width

If the layout starts breaking around 920px, your Tablet maximum may need to be closer to 960px than the WordPress default of 782px.

4. Continue Toward Mobile

Keep narrowing the layout. Find the point where the Tablet treatment no longer works and the Mobile layout should take over.

5. Test More Than One Page

Do not choose theme-wide breakpoints based on one hero section. Test:

• The header.
• Footer columns.
• Blog archives.
• Single posts.
• Landing pages.
• Pricing tables.
• WooCommerce pages if applicable.

The best breakpoints are the ones that solve the most common layout problems across the whole theme.

Example Breakpoint Strategies

There is no perfect set of values for every website, but these examples show how different themes may approach the decision.

Simple Blog Theme

"viewport": {
  "mobile": "480px",
  "tablet": "782px"
}

The defaults may already work well because the layout is mostly a readable content column with a simple header.

Business or Agency Theme

"viewport": {
  "mobile": "600px",
  "tablet": "960px"
}

This provides more room for larger navigation menus, multi-column service sections, and wide marketing layouts.

Store or Catalog Theme

"viewport": {
  "mobile": "640px",
  "tablet": "1024px"
}

A product-focused design may need to adjust grids, filters, galleries, and cart layouts earlier than a blog.

These values are examples. Test your own content before using them.

Should You Copy Framework Breakpoints?

You can align WordPress with an existing frontend system, but do not copy framework breakpoints without checking the theme.

Matching an established design system can be helpful when:

• The theme already uses those breakpoints in its CSS.
• Components were designed around the same viewport ranges.
• The development team needs one consistent source of truth.
• WordPress block styles must align with an existing application frontend.

It becomes a problem when framework values are copied simply because they are familiar.

Your content may break at 890px even if your framework’s nearest breakpoint is 768px. Design around the content, then align the tools.

Keep theme.json and Custom CSS Aligned

If your theme still uses custom media queries, make sure they follow the same breakpoint logic as settings.viewport.

Avoid this type of mismatch:

• theme.json Tablet ends at 960px.
• Navigation CSS switches at 782px.
• Product grid CSS switches at 1024px.
• A plugin assumes Mobile ends at 600px.

That creates confusing ranges where one part of the page thinks it is Desktop while another behaves like Tablet.

A clean theme should document its responsive system and reuse those values wherever possible.

Do Custom Breakpoints Change Core Block Layouts?

Custom viewport settings provide a shared definition for responsive styles and block visibility. That does not necessarily mean every historical hardcoded behavior inside every block or third-party plugin will automatically adopt your values.

You should still test:

• Navigation collapse behavior.
• Columns stacking.
• Grid layouts.
• Third-party block plugins.
• WooCommerce blocks.
• Custom blocks with their own responsive controls.

A plugin may use its own breakpoints. A custom block may ship separate CSS media queries. The theme configuration becomes an important source of truth, but older or custom code may still need alignment.

Custom Breakpoints and Fluid Typography

Fluid typography and viewport breakpoints solve related but different problems.

Fluid typography lets text scale gradually between minimum and maximum values. Breakpoint-based responsive styling applies specific values within named viewport ranges.

You can use both. A theme may provide fluid font presets as the default and still let editors apply a smaller Mobile override to a special hero heading.

Editing a Parent Theme vs Child Theme

Do not modify a third-party parent theme’s theme.json directly unless you maintain that theme yourself.

A theme update may overwrite your changes.

For a third-party project:

• Use a child theme where appropriate.
• Copy only the configuration you need.
• Test how the parent and child theme.json data are merged.
• Keep a record of custom breakpoint choices.
• Retest after parent-theme updates.

If the theme is custom-built for your project, place the viewport settings in the main theme configuration and treat them as part of the design system.

Testing Custom Viewport Breakpoints

Custom breakpoints should be tested in both the editor and the frontend.

Editor Tests

• Open Desktop, Tablet, and Mobile preview states.
• Resize the editor canvas around each breakpoint.
• Confirm responsive styles switch at the expected widths.
• Check viewport-based block visibility.
• Save, reload, and confirm values remain intact.
• Test Global Styles and individual block overrides.

Frontend Tests

• Resize the browser one pixel below and above each breakpoint.
• Test real mobile and tablet devices where possible.
• Check navigation.
• Check long headings.
• Check wide tables and code blocks.
• Check cards, grids, and columns.
• Check footer layouts.
• Check logged-in and logged-out states.

Pay special attention to the boundary itself. A design that works at 959px and 961px but jumps awkwardly at 960px still needs refinement.

Testing Checklist for Theme Developers

• theme.json uses version 3.
• settings.viewport is in the correct location.
• Mobile is lower than Tablet.
• Both values use valid CSS length strings.
• The JSON file contains no trailing commas.
• The theme loads without schema errors.
• Responsive block styles use the custom values.
• Block visibility uses the custom values.
• Existing CSS media queries are aligned.
• Navigation and Columns behavior are tested separately.
• Third-party blocks are reviewed.
• Editor and frontend output match.
• The theme is tested without the Gutenberg plugin if Core support is required.

Common Mistakes

• Putting viewport outside the settings object.
• Defining a Mobile value larger than Tablet.
• Expecting a separate Desktop value.
• Choosing breakpoints from device names instead of layout behavior.
• Adding too many custom CSS breakpoints outside WordPress.
• Assuming every third-party block will use the theme values.
• Testing only the editor preview.
• Editing a parent theme that will overwrite the change.
• Changing breakpoints after editors have already created many responsive overrides without retesting them.

Changing Breakpoints on an Existing Site

Changing breakpoint values on a new theme is straightforward. Changing them after a site already contains responsive styles and visibility rules requires more care.

Existing content may have been designed around the previous viewport ranges. When the breakpoints move, those same Tablet and Mobile values will start applying at different widths.

Before changing an established theme:

1. Create a full backup.
2. Clone the site to staging.
3. Record the old breakpoint values.
4. Apply the new values.
5. Test major templates and patterns.
6. Check pages with local responsive overrides.
7. Check blocks hidden by viewport.
8. Review analytics for common visitor widths if available.
9. Deploy only after the full site passes testing.

A breakpoint change is a design-system change. Treat it like one.

Recommended Practical Setup

For many business-oriented block themes, this is a sensible starting point:

{
  "version": 3,
  "settings": {
    "viewport": {
      "mobile": "600px",
      "tablet": "960px"
    }
  }
}

This gives smaller screens a little more room than the WordPress defaults and lets Tablet cover widths where full desktop navigation and multi-column sections often start feeling tight.

However, it is still only a starting point. Test the theme’s actual navigation, content, grids, forms, and footer before committing to it.

Final Verdict

Custom viewport breakpoints in theme.json give block themes a much-needed way to align WordPress responsive features with the theme’s real design system.

The setup is simple: add mobile and tablet values inside settings.viewport. Mobile applies up to its maximum width, Tablet covers the range above Mobile through its own maximum, and Desktop handles everything wider.

The more important work is choosing the values well.

Do not pick breakpoints because a popular CSS framework uses them. Narrow your layout gradually, watch where the design becomes uncomfortable, and define the breakpoints around those moments.

Keep the system small, consistent, and documented. Align any custom CSS with the same values, test third-party blocks separately, and review existing responsive content before changing breakpoints on a live site.

Used properly, settings.viewport gives responsive styling and block visibility one shared foundation—and makes WordPress feel much closer to a complete theme design system.