Fluid typography in theme.json, and why inline font sizes break mobile
How to configure clamp-based fluid typography in theme.json, why manual font overrides break mobile viewports, and how to structure portable type steps.
To make WordPress type scale with the screen, turn on fluid typography in theme.json under settings.typography.fluid, then choose named font sizes rather than typing pixels into the block sidebar.
Setting custom pixel font sizes inside the block inspector breaks responsive layouts on smaller screens. When you assign an explicit font size like 56px to a heading in the editor sidebar, WordPress writes an inline CSS style attribute directly into the block markup. That fixed pixel value overrides viewport scaling, forcing a desktop-sized headline onto mobile screens until you write custom CSS media queries to fix it.
Modern block themes solve this globally through theme.json fluid typography. When enabled, WordPress compiles named typography steps into dynamic CSS clamp() functions that scale smoothly between mobile and desktop viewports without custom stylesheets.
How WordPress compiles fluid typography into clamp rules#
When you enable fluid typography in theme.json, WordPress intercepts your font size declarations and compiles them into mathematical clamp() formulas. The calculation uses minimum and maximum viewport thresholds to scale the font linearly between screen widths:
{
"version": 3,
"settings": {
"typography": {
"fluid": true,
"fontSizes": [
{
"slug": "small",
"size": "0.875rem",
"name": "Small"
},
{
"slug": "medium",
"size": "1rem",
"name": "Medium"
},
{
"slug": "large",
"size": "1.75rem",
"name": "Large",
"fluid": {
"min": "1.25rem",
"max": "1.75rem"
}
},
{
"slug": "x-large",
"size": "2.75rem",
"name": "Extra Large",
"fluid": {
"min": "1.75rem",
"max": "2.75rem"
}
},
{
"slug": "xx-large",
"size": "4rem",
"name": "Colossal",
"fluid": {
"min": "2.25rem",
"max": "4rem"
}
}
]
}
}
}
On render, WordPress outputs CSS custom properties on :root that define the dynamic scaling curve:
:root {
--wp--preset--font-size--small: 0.875rem;
--wp--preset--font-size--medium: 1rem;
--wp--preset--font-size--large: clamp(1.25rem, 1.25rem + ((1vw - 0.2rem) * 0.781), 1.75rem);
--wp--preset--font-size--x-large: clamp(1.75rem, 1.75rem + ((1vw - 0.2rem) * 1.563), 2.75rem);
--wp--preset--font-size--xx-large: clamp(2.25rem, 2.25rem + ((1vw - 0.2rem) * 2.734), 4rem);
}
When a heading or paragraph uses the has-x-large-font-size class, the browser recalculates the rendered size continuously as the viewport changes width. No breakpoint jumps or device-specific media queries are needed.
Here is an example of an editorial hero composition that utilizes monumental display typography while maintaining fluid scaling across viewports:
Configuring global fluid boundaries#
By default, WordPress calculates fluid curves between a minimum viewport width of 320px and a maximum viewport width of 1600px. If your site layout caps at a narrower container (for example, 1200px), you can define explicit viewport boundaries inside the settings.typography.fluid object:
{
"version": 3,
"settings": {
"typography": {
"fluid": {
"minViewportWidth": "375px",
"maxViewportWidth": "1280px"
}
}
}
}
This prevents headline sizes from expanding beyond their intended proportions on ultra-wide desktop monitors while preserving readable proportions on mobile phones.
Why inline font sizes break pattern portability#
When you paste a third-party block pattern or export a custom layout, inspect the block markup for hardcoded fontSize values:
<!-- wp:heading {"style":{"typography":{"fontSize":"48px"}}} -->
<h2 class="wp-block-heading" style="font-size:48px">Core capabilities</h2>
<!-- /wp:heading -->
This markup causes two distinct production issues:
- Mobile overflow: A
48pxheading on a360pxmobile screen forces long words to break awkwardly or cause horizontal viewport scrolling. - Theme immunity: Because the inline
style="font-size:48px"attribute has higher CSS specificity than theme presets, updating your theme's typography scale intheme.jsonwill not affect this block.
Well-structured pattern markup references the typography slug attribute instead:
<!-- wp:heading {"fontSize":"x-large"} -->
<h2 class="wp-block-heading has-x-large-font-size">Core capabilities</h2>
<!-- /wp:heading -->
By referencing the slug, the block automatically uses the active theme's fluid clamp() formula.
Line height and letter spacing in fluid hierarchies#
Scaling font size alone is insufficient for clean typography. Large display headlines require tighter line heights and subtly negative letter spacing, while small body text demands generous leading to remain readable:
- Display sizes (
xx-large): SetlineHeightto1.05to1.15. A fluid heading that doubles in font size on desktop looks uncomfortably loose if it retains a1.5line height. - Body text (
medium,small): Maintain alineHeightof1.5to1.7to ensure comfortable reading measure across wide paragraphs. - Letter spacing: In
theme.json, assign subtle negative tracking (-0.02emto-0.03em) to oversized headline presets to give display type a confident, editorial feel.
WCAG 2.1 compliance and text zooming#
Fluid typography calculated with CSS clamp() must respect accessibility guidelines. WCAG Success Criterion 1.4.4 (Resize Text) requires that text can be zoomed up to 200 percent without loss of content or functionality.
If a developer writes a naive fluid formula using only viewport units (for example, font-size: 5vw), the text does not scale when a visually impaired user zooms their browser using Cmd + or browser zoom controls. Viewport units depend on window dimensions, not user font preferences.
WordPress core's fluid typography formula avoids this failure by combining rem base units with a linear viewport factor:
/* Safe: combines rem base with linear viewport scaling */
clamp(1.75rem, 1.75rem + ((1vw - 0.2rem) * 1.563), 2.75rem)
Because the minimum and maximum boundaries and the formula base use rem, the font size responds immediately when a user adjusts their default browser font size or zooms the page, fulfilling WCAG AA requirements out of the box.
Hosting local fonts in theme.json without external layout shifts#
Fluid typography performs best when web fonts load with zero layout shift. If a custom web font takes hundreds of milliseconds to arrive from an external CDN, the browser initially renders the system fallback font. When the web font swaps in, different letter widths cause headings to re-wrap, generating Cumulative Layout Shift (CLS).
In modern block themes, define local font assets directly inside settings.typography.fontFamilies:
{
"fontFamily": "'Inter', sans-serif",
"name": "Inter",
"slug": "body",
"fontFace": [
{
"fontFamily": "Inter",
"fontWeight": "400 700",
"fontStyle": "normal",
"fontDisplay": "swap",
"src": ["file:./assets/fonts/inter-variable.woff2"]
}
]
}
Using a local variable font format (.woff2) reduces HTTP request count, eliminates third-party DNS lookups, and provides precise font-weight interpolation for your fluid scale.
Auditing typography scaling across viewports#
To verify that your site typography scales smoothly:
- Open Chrome DevTools and toggle Device Mode (
Cmd + Shift + M). - Drag the viewport slider slowly from
320pxup to1400pxwhile inspecting primary headlines. The computedfont-sizein the Computed Styles panel should increase smoothly rather than jumping at arbitrary breakpoints. - Check for awkward line wraps: ensure three-word headings do not wrap onto four lines on mobile screens.
- Scan your database with WP-CLI for hardcoded font sizes: ``
bash # Find posts containing inline font-size styles wp db query "SELECT ID, post_title FROM wp_posts WHERE post_content LIKE '%style="font-size:%' AND post_status = 'publish';"``
Every Pattern Paste Core Pattern relies on standard typography slugs rather than inline pixel sizes, ensuring headings scale fluidly on every viewport. Explore the catalogue to see Core Patterns that inherit your theme and Interactive Patterns with curated styling.
From the library






