iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Antihost offers managed WordPress hosting with free migration, one-click staging and a 14-day free trial.
wp_is_mobile() is WordPress’s server-side boolean check for deciding whether the current request is classified as mobile. It returns true for mobile-classified requests, including tablets, and false for other requests. Use it when PHP needs to change a payload, resource, or device-sensitive feature—not when you need a CSS breakpoint or an exact screen width.
The function uses the Sec-CH-UA-Mobile client hint when available and otherwise examines user-agent tokens. If your HTML changes according to the result, your page cache must keep separate mobile and non-mobile variants.
What wp_is_mobile() does
Call the function anywhere WordPress has loaded its core functions, such as a theme template, a plugin callback, or an enqueue hook:
<?php
if ( wp_is_mobile() ) {
// Render a mobile-classified response.
} else {
// Render the standard response.
}
The return value is a PHP boolean. A result of true means WordPress classified the request as mobile; false means it did not. The classification is based on the request’s advertised device characteristics, not on a measurement of the browser’s current layout viewport.
#1 Best Overall
WordPress includes tablets in the mobile result. A large tablet and a small phone can therefore follow the same branch, while a desktop browser window narrowed to phone-like dimensions can still follow the non-mobile branch.
Basic theme usage
Render different server-side content
This pattern keeps both variants in the document and lets PHP choose which one to send:
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware match<?php if ( wp_is_mobile() ) : ?>
<section class='mobile-summary'>
<h2>At a glance</h2>
<p>A short summary for mobile-classified requests.</p>
</section>
<?php else : ?>
<section class='desktop-summary'>
<h2>Full details</h2>
<p>The complete version for other requests.</p>
</section>
<?php endif; ?>
Keep the markup accessible in either branch. A server decision should not remove essential information, navigation, form controls, or functionality from people whose device is classified unexpectedly.
Choose a device-sensitive feature
A branch can be useful when the two request types genuinely need different work, such as selecting a lighter server-rendered payload or avoiding an expensive capability on a constrained device:
<?php
if ( wp_is_mobile() ) {
$summary_mode = 'compact';
$items_per_page = 10;
} else {
$summary_mode = 'full';
$items_per_page = 25;
}
These values are an application decision, not a promise about physical screen size. Treat them as defaults that can be overridden by user controls or later client-side behavior when appropriate.
Conditionally enqueue an asset
You can make a server-side choice in an enqueue callback. The styles still need to be responsive because the classification does not describe an exact viewport:
Free tools Windows power users keep installed
One-click scans. No signup required.
<?php
add_action( 'wp_enqueue_scripts', function () {
if ( wp_is_mobile() ) {
wp_enqueue_style(
'site-mobile-enhancements',
get_theme_file_uri( '/assets/mobile-enhancements.css' ),
array(),
null
);
}
} );
Use this only when sending the additional asset to one request class has a clear benefit. If the difference is purely visual, a single responsive stylesheet is usually simpler and avoids device-specific cache variants.
How WordPress classifies a request
Client hint in WordPress 6.4 and later
WordPress 6.4.0 added a check for the Sec-CH-UA-Mobile request header. When that header is present with the exact value ?1, WordPress treats the request as mobile.
The header is a browser-provided client hint. It is not a viewport-width value and does not tell WordPress whether a device is a phone, tablet, foldable, or a particular CSS pixel width.
User-agent fallback
If the client hint is absent, WordPress falls back to matching mobile-oriented tokens in the user-agent string. The documented set includes:
MobileAndroidSilk/KindleBlackBerryOpera MiniOpera Mobi
This fallback explains why changing or spoofing a user agent can change the result. It also means that unusual browsers, bots, embedded webviews, and future device identifiers may not behave exactly as you expect. Test the actual user agents that matter to your site rather than assuming the label shown by a browser is enough.
The result passes through a filter
After WordPress computes the initial value, it applies the wp_is_mobile filter. A plugin or theme can therefore change the final boolean before your code receives it. The filter was introduced in WordPress 4.9.0.
What the function cannot tell you
It does not measure viewport width
wp_is_mobile() cannot answer questions such as:
- Is the viewport narrower than 768 CSS pixels?
- Is the browser currently in portrait orientation?
- How many CSS pixels are available after a sidebar opens?
- Is a desktop window being resized to a phone-like width?
Those are browser-layout questions. The official WordPress guidance says the function is not a substitute for CSS media queries or styling per platform.
Use CSS for layout
Keep layout rules in responsive CSS:
.card-grid {
display: grid;
grid-template-columns: repeat(3, minmax(0, 1fr));
gap: 1.5rem;
}
@media (max-width: 48rem) {
.card-grid {
grid-template-columns: 1fr;
}
}
This works for a narrow desktop window, a tablet, a phone, split-screen mode, zoomed content, and other situations that server-side device classification cannot distinguish reliably.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Use the block editor’s viewport store in client-side code
When JavaScript in the block editor needs a viewport breakpoint, WordPress documents the core/viewport data store and its isViewportMatch selector. That client-side mechanism answers a different question from wp_is_mobile(): it evaluates the browser viewport rather than the incoming request’s device classification.
Choosing the right decision layer
| Requirement | Use | Primary signal | Cache consequence |
|---|---|---|---|
| Change visual layout at a breakpoint | Responsive CSS media queries | Browser viewport | Usually one HTML response can serve all widths |
| Choose a smaller server-rendered payload for a mobile-classified request | wp_is_mobile() |
Client hint or user-agent classification | HTML or response caches may need mobile and non-mobile buckets |
| React or block-editor behavior tied to viewport width | core/viewport and isViewportMatch |
Client-side viewport breakpoint | Normally handled after delivery, without separate HTML variants |
| Override a project-specific classification rule | wp_is_mobile filter |
Your documented PHP rule | Every override must agree with cache variation |
Full-page caching: the failure that surprises developers
If PHP produces different HTML, headers, or server responses according to wp_is_mobile(), a cache must store and retrieve those variants separately. A cache that stores only one copy can give a mobile-classified response to a desktop visitor, or the desktop response to a mobile visitor.
Why the problem occurs
- A mobile-classified request reaches WordPress first and generates compact markup.
- The page cache stores that response under the URL.
- A non-mobile request arrives later for the same URL.
- The cache serves the stored response without running PHP, so the second request receives the wrong variant.
The reverse order creates the same defect. Purging the cache may make the problem appear to disappear until the other device class becomes the first visitor after the purge.
Configure variation before enabling the branch
Use the cache system’s mobile-device variation feature if it provides one, or configure the cache layer to maintain distinct mobile and non-mobile buckets. The exact setting name and implementation depend on the hosting or caching provider; WordPress does not prescribe one universal control.
Do not assume that a browser’s responsive preview is testing cache variation. A preview may change the viewport while keeping a desktop user agent, which exercises CSS but not necessarily the server classification.
Test the cached result
- Publish or update the code that changes output.
- Purge the relevant page and any upstream CDN or reverse-proxy cache.
- Request the page while logged out with a mobile-classified user agent.
- Confirm the mobile branch appears, then record the response.
- Request the same URL while logged out with a desktop user agent.
- Confirm the non-mobile branch appears rather than the earlier cached HTML.
- Repeat the sequence in the opposite order after another purge.
Test a page that is actually cached. Logged-in sessions, preview modes, development bypasses, and cache-busting query strings can skip the path that causes production failures.
Customizing the result with the wp_is_mobile filter
The filter receives the boolean computed by core. Return a deliberate boolean only when a project-specific rule is justified:
<?php
add_filter( 'wp_is_mobile', function ( $is_mobile ) {
// Apply a documented project rule here when necessary.
return $is_mobile;
} );
A real override might inspect a controlled request condition, but it should be narrow, easy to audit, and covered by tests. Avoid broad string matching that silently reclassifies unrelated browsers.
Filter safety checklist
- Document why the default client-hint and user-agent result is insufficient.
- Return only
trueorfalse, not a truthy string or an unrelated value. - Ensure the rule runs consistently for every request that can be cached.
- Update cache variation whenever the rule changes.
- Check both logged-in and logged-out behavior if the site uses different execution paths.
- Retest after WordPress, theme, plugin, proxy, or CDN changes.
Changing this filter changes the meaning of every downstream branch and can invalidate existing cache entries. Treat it as application-wide behavior rather than a local formatting tweak.
Version history and compatibility
| WordPress version | Change | Practical meaning |
|---|---|---|
| 3.4.0 | wp_is_mobile() introduced |
The core function became available for server-side mobile classification. |
| 4.9.0 | wp_is_mobile filter introduced |
The computed boolean can be modified before your code uses it. |
| 6.4.0 | Client-hint check added | Core checks Sec-CH-UA-Mobile for the exact mobile value ?1 before using the documented user-agent fallback. |
On older WordPress versions, behavior differs because the client-hint check did not yet exist. If a site supports multiple core versions, test the oldest supported version and do not assume that all requests are classified using the current algorithm.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Common mistakes and fixes
Mistake: using it as a breakpoint
Symptom: A tablet receives a phone layout, or a narrow desktop window receives the desktop layout.
Fix: Move layout decisions to CSS media queries. Reserve the PHP branch for payload or capability decisions that truly belong on the server.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Mistake: expecting a phone-only result
Symptom: Tablet traffic follows the same branch as phone traffic.
Fix: Treat true as mobile-classified, not as “small phone.” If you need a finer distinction, define and test a separate, documented capability or client-side rule rather than inferring screen width from this boolean.
Best Value
Mistake: testing only with an emulator
Symptom: Development looks correct, but real visitors see the wrong branch.
Fix: Test real mobile and desktop user agents, the presence or absence of the client hint, logged-out sessions, and the production cache path.
Recommended Free Tools
Mistake: forgetting the cache after adding a branch
Symptom: One device class consistently sees another class’s HTML.
Fix: Purge all relevant layers, configure separate mobile/non-mobile buckets, and repeat the opposite-order test described above.
Mistake: assuming the function runs for cached hits
Symptom: A code change appears ineffective for some visitors.
Fix: Remember that a full-page cache can serve HTML without executing PHP. Verify the cache key and purge state before debugging the conditional itself.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesMistake: hiding essential content in one branch
Symptom: Keyboard, assistive-technology, or unexpected-device users cannot access the same information or controls.
Fix: Keep both branches functionally complete, use semantic HTML, and use CSS to adapt presentation wherever possible.
A practical decision checklist
- Is the decision about server payload, device capability, or an expensive server-side feature? If yes, consider
wp_is_mobile(). - Is the decision about columns, spacing, typography, visibility, or a precise width? Use responsive CSS instead.
- Could a tablet and phone reasonably need different treatment? Do not assume this function can distinguish them.
- Will the response differ for the two results? Confirm cache variation before deployment.
- Are you adding a filter? Document the rule, return a boolean, and include it in cache testing.
- Have you tested client-hint and user-agent fallback behavior on the WordPress versions you support?
Putting it all together
A safe implementation separates server decisions from presentation decisions:
<?php
$is_mobile_request = wp_is_mobile();
if ( $is_mobile_request ) {
$content_mode = 'compact';
} else {
$content_mode = 'full';
}
?>
<article class='content content--<?php echo esc_attr( $content_mode ); ?>'>
<h1><?php the_title(); ?></h1>
<div class='content__body'>
<?php the_content(); ?>
</div>
</article>
The PHP chooses a server-rendered mode, while the accompanying CSS should still handle intermediate widths and unusual viewport conditions. If this markup is cached, configure the cache to vary on the same mobile/non-mobile classification before shipping it.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
