Free tools Windows power users keep installed
One-click scans. No signup required.
Use wp_is_mobile() when PHP needs a boolean decision about whether the current request comes from a mobile-classified device. It returns true for mobile-classified requests, including tablets, and false for other requests. It does not measure CSS viewport width, choose responsive breakpoints, or replace media queries.
Antihost offers managed WordPress hosting with free migration, one-click staging and a 14-day free trial.
What wp_is_mobile() does
wp_is_mobile() is a WordPress core function for server-side device classification. Your PHP runs on the server, WordPress examines request information, and the function returns a boolean:
As an Amazon Associate I earn from qualifying purchases.
true: WordPress classifies the request as mobile.false: WordPress classifies the request as non-mobile.
The result is intended for decisions about device capability, available resources, or the amount of server-rendered content. For example, a theme could send a shorter server-rendered summary to a mobile-classified request and a longer version to other requests.
“Mobile” here is a request classification, not a measurement of the browser window. A phone, tablet, and another mobile-classified device can all return true despite having very different screen dimensions. Conversely, a desktop browser window can be made narrow without becoming a mobile-classified request.
Basic usage in a theme
Call the function anywhere WordPress has loaded its core functions, such as a theme template or server-side plugin code. The simplest conditional is:
<?php if ( wp_is_mobile() ) : ?>
<p class="mobile-summary">Short version for mobile-classified requests.</p>
<?php else : ?>
<p class="desktop-summary">Full version for other requests.</p>
<?php endif; ?>The alternative PHP syntax is useful when the branch contains more than a small template fragment:
<?php
if ( wp_is_mobile() ) {
// Keep server-rendered output small or adapt a device-sensitive feature.
} else {
// Render the standard version.
}
?>Both examples make a server-side choice before the response reaches the browser. They do not inspect the viewport after the page loads.
Returning the value instead of branching
Because the function returns a boolean, you can assign it to a variable when several decisions need the same classification:
<?php
$is_mobile_request = wp_is_mobile();
if ( $is_mobile_request ) {
$summary_length = 'short';
} else {
$summary_length = 'full';
}
?>Use one value for a request rather than scattering unrelated calls through a template. This keeps the decision visible and makes it easier to audit when caching or filters are involved.
Rank #2
What WordPress checks internally
WordPress first checks the Sec-CH-UA-Mobile request header. The exact value ?1 is treated as mobile. If that header is absent, WordPress falls back to matching mobile-related user-agent tokens, including:
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →MobileAndroidSilk/KindleBlackBerryOpera MiniOpera Mobi
The computed boolean is then passed through the wp_is_mobile filter. Code attached to that filter can deliberately change the final result before your theme or plugin receives it.
The function was introduced in WordPress 3.4.0. WordPress 6.4.0 added the client-hint check, and the wp_is_mobile filter was introduced in WordPress 4.9.0. Those version milestones matter when maintaining older installations: behavior on a pre-6.4.0 site does not include the client-hint step, and the filter is not available before 4.9.0.
What the function does not detect
WordPress explicitly says that this function “is not a substitute for CSS media queries or styling per platform.” It cannot tell your PHP whether the viewport is 320 pixels, 768 pixels, or 1,440 pixels wide, and it cannot select an exact responsive breakpoint.
- It does not return a viewport width.
- It does not identify a particular CSS breakpoint.
- It does not tell you whether a desktop user resized a browser window.
- It does not make markup responsive by itself.
- It does not replace CSS media queries.
Keep the HTML produced by either branch usable at different widths. A mobile-classified request may still be viewed on a relatively wide tablet, while a non-mobile request may be viewed in a narrow desktop window.
Rank #3
Choose the right layer for the decision
| Approach | Decision layer | Primary signal | Best use | Cache effect |
|---|---|---|---|---|
wp_is_mobile() |
Server-side PHP | Client hint or user-agent classification | Device-sensitive payload, capability, or resource decisions | Different HTML can require separate mobile and non-mobile cache buckets |
| CSS media queries | Browser presentation | Current viewport and media features | Layout, spacing, visibility, typography, and responsive styling | Normally keeps one HTML response usable across widths |
| Block-editor viewport APIs | Client-side JavaScript | Viewport breakpoint matching | Viewport-aware behavior in block-editor code | Usually avoids separate server-rendered HTML variants |
For client-side block-editor code that needs viewport breakpoints, WordPress documents the core/viewport store and its isViewportMatch selector. That is a different problem from classifying the incoming PHP request.
Using it without making layout brittle
Use CSS for visual changes
If the requirement is “stack these columns on small screens,” “reduce this padding,” or “hide this navigation control below a breakpoint,” write responsive CSS. Both server branches should remain valid if the viewport changes after the initial response, if a tablet is classified as mobile, or if a desktop window is narrow.
Use PHP for payload or capability changes
A server-side branch is appropriate when the response itself should differ for a device class—for example, a deliberately shorter server-rendered summary or a device-sensitive feature whose resource cost is inappropriate for a mobile-classified request. Keep the reason for the branch specific and documented; “mobile looks narrower” is a CSS concern, not a reliable PHP rule.
Combine both when necessary
A common safe pattern is to render a mobile-classified request with a smaller initial payload while applying the same responsive CSS to every version. The function decides what the server sends; CSS still handles the final presentation.
Step-by-step: add a mobile-aware branch to a theme
- Define the actual requirement. Write down whether you are reducing server-rendered payload or merely changing visual layout. If it is only layout, stop and use CSS media queries.
- Choose the template location. Open the theme template responsible for the output you want to vary. Make the smallest branch that satisfies the requirement.
- Call the function in PHP. Use
if ( wp_is_mobile() )and provide anelsebranch for non-mobile requests. Do not assume thattruemeans “phone.” - Keep both outputs valid. Give both branches appropriate markup and classes. Their CSS must remain responsive because classification is not viewport measurement.
- Test both classifications. Check a mobile-classified user agent and a desktop user agent, and inspect the generated HTML rather than relying only on how one browser window looks.
- Review caching before launch. If the full response differs, verify that the page cache can store separate mobile and non-mobile variants.
Full-page caching: the failure that surprises people
If a page cache stores the HTML generated for one result of wp_is_mobile() and serves that same response to every request, visitors can receive the wrong branch. A mobile response may be delivered to a desktop visitor, or a non-mobile response may be delivered to a mobile-classified visitor.
The official reference warns that a cache must vary by mobile versus non-mobile status whenever the response differs. The exact setting name is provider-specific; WordPress does not prescribe one universal checkbox or configuration key for every cache system.
How to make a cached implementation safe
- Identify every response difference. Include differences produced directly by the function and differences produced by code hooked to
wp_is_mobile. - Configure two cache buckets. Set the page cache to vary between mobile-classified and non-mobile requests. Follow your cache provider’s terminology rather than copying a setting name from another product.
- Purge existing pages. Old entries can continue serving the wrong variant after you change the PHP or cache rules.
- Test while logged out. Many full-page caches bypass authenticated sessions, so an administrator view does not prove that public caching is correct.
- Request the same URL from both classes. Use a mobile-classified user agent and a desktop user agent after the purge. Compare the returned HTML and the cache headers or diagnostics supplied by your provider.
- Retest after edits. Any later template change that alters one branch requires another purge and a two-class verification.
If you cannot create correct mobile and non-mobile cache buckets, avoid making the cached HTML depend on wp_is_mobile(). Use one responsive response and let CSS handle presentation instead.
Customizing the result with the wp_is_mobile filter
The filter receives the boolean calculated by WordPress. A callback can return a deliberate boolean when a project-specific rule justifies overriding the default classification:
<?php
add_filter( 'wp_is_mobile', function ( $is_mobile ) {
// Return a deliberate boolean only when a documented project rule is justified.
return $is_mobile;
} );The example leaves the value unchanged; replace the return expression only when you have a clear rule. Keep overrides narrow, document why they exist, and consider their cache consequences. Changing the classification changes which mobile or non-mobile response is valid, so a filter override can make an otherwise correct cache configuration unsafe.
When an override is justified
- The project has a documented request rule that the default client-hint and user-agent classification cannot express.
- The rule has a predictable result for every request that can be cached.
- The cache varies according to the resulting classification, not merely the original user agent.
- The team can test the override when browsers, proxies, or request headers change.
When not to override
- To emulate a CSS breakpoint in PHP.
- To treat every narrow desktop window as mobile.
- To fix a layout problem that belongs in responsive CSS.
- Without updating cache variation and test coverage.
Troubleshooting incorrect results
The function returns false on a phone
Check the request that actually reached WordPress. The function relies first on Sec-CH-UA-Mobile: ?1 when present and otherwise on recognized user-agent tokens. A proxy, testing tool, or unusual browser identifier may not provide either signal in the expected form. Inspect the request headers and user-agent seen by the origin, then test again without a stale cached response.
The function returns true on a tablet
This is expected. Tablets are included in the mobile-classified result when the request matches the client-hint or user-agent logic. Do not treat the boolean as a phone-only test or as evidence of a particular width.
A desktop visitor sees the mobile markup
First purge the page cache and request the URL as a logged-out desktop user. If the response remains wrong, verify that the cache has separate mobile and non-mobile buckets and that an override on wp_is_mobile is not changing the result. Also check whether the desktop request is being identified by a mobile token.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →A mobile visitor sees the desktop markup
Perform the inverse test: purge, request as a mobile-classified user agent, and inspect the origin response. Confirm that the mobile bucket is enabled and that no filter callback forces false. If the page is intentionally one responsive HTML response, the absence of a mobile branch is not an error.
The layout is wrong even though the boolean is correct
That indicates a presentation problem, not a classification problem. Add or correct CSS media queries and keep the markup usable across widths. A correct true value cannot tell PHP the current viewport width.
Version and compatibility notes
| Capability | WordPress version noted in the reference | Meaning |
|---|---|---|
wp_is_mobile() function |
Introduced in 3.4.0 | The core function became available. |
wp_is_mobile filter |
Introduced in 4.9.0 | Code can alter the calculated boolean through the filter. |
Sec-CH-UA-Mobile check |
Added in 6.4.0 | WordPress checks the client hint value ?1 before its fallback matching. |
These are implementation milestones, not promises that every browser sends the client hint. The fallback user-agent matching remains part of the function’s behavior when the header is absent.
A practical decision checklist
- Do I need a server-side boolean, or do I really need a viewport breakpoint?
- Will tablets be acceptable in the same branch as phones?
- Does the response differ in HTML, data volume, or resource behavior?
- Can my page cache maintain separate mobile and non-mobile buckets?
- Have I tested logged-out cached requests from both classifications after a purge?
- Is any
wp_is_mobilefilter documented and included in cache testing? - Do both branches remain responsive if the viewport does not match the device class?
Bottom line
wp_is_mobile() is a server-side mobile-device classifier. Use its boolean for deliberate payload or capability decisions, remember that tablets can return true, and understand that WordPress bases the result on a client hint or user-agent matching before applying the wp_is_mobile filter. Use CSS media queries for layout and viewport behavior. If the function changes cached HTML, configure separate mobile and non-mobile cache buckets and verify both paths with logged-out tests.
Outdated 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 matchWindows 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 reinstallQuick 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.
