How to Detect Device Form Factor in Salesforce LWC (The Right Way)

In plain words: When building Salesforce components, you often need to show a different layout for mobile users than you do for desktop users. Instead of writing custom JavaScript to calculate screen width, Salesforce provides a built-in module called @salesforce/client/formFactor. This module automatically tells your component if the user is on a phone, tablet, or desktop, so you can adjust the UI instantly.

In today's ecosystem, your users will access Salesforce from massive desktop monitors, tablets out in the field, and smartphones on the train. Building user-friendly and highly responsive interfaces is no longer optional—it is a requirement.

Many developers coming from a standard web development background try to handle this in Lightning Web Components (LWC) by using traditional browser properties like window.innerWidth. Let's look at why that is a mistake in Salesforce, and how to do it the official way.

Developer Trap: Avoid window.innerWidth
Do not use standard JavaScript window resizing properties to guess the device type in LWC. Salesforce apps run in complex containers (like the Salesforce Mobile App, Field Service App, or embedded communities). Relying on window.innerWidth is prone to bugs, fails to account for device orientation changes properly, and violates Salesforce performance best practices.

The Solution: The Form Factor Module

Salesforce provides a native hardware module specifically designed to evaluate the hardware running your component. By importing @salesforce/client/formFactor, you can securely capture the environment.

The module returns one of three simple string values:

• Large: The component is running on a desktop client.
• Medium: The component is running on a tablet client.
• Small: The component is running on a phone client.

Step 1: Write the JavaScript Controller

First, create a new LWC. In your JavaScript file, we will import the form factor module and create boolean (true/false) properties to tell our HTML template what type of device is currently active.

import { LightningElement } from 'lwc';
// Import the native Salesforce form factor module
import FORM_FACTOR from '@salesforce/client/formFactor';

export default class DynamicDeviceLayout extends LightningElement {
    
    // Check if the current device is a desktop
    get isDesktop() {
        return FORM_FACTOR === 'Large';
    }

    // Check if the current device is a tablet
    get isTablet() {
        return FORM_FACTOR === 'Medium';
    }

    // Check if the current device is a mobile phone
    get isMobile() {
        return FORM_FACTOR === 'Small';
    }
}

Step 2: Create the Dynamic HTML Template

Now that our JavaScript controller knows the device type, we can use the modern lwc:if and lwc:elseif directives to render completely different HTML structures based on the device.

Real-Life Example: Mobile-Friendly Buttons
On a desktop, you might want to show a complex data table. But on a mobile phone, that table will break the screen. Instead, you can use form factors to completely hide the table and show a stack of summary cards for mobile users.

<template>
    <lightning-card title="Responsive UI Example" icon-name="custom:custom63">
        <div class="slds-p-around_medium">
            
            <!-- Desktop View -->
            <template lwc:if={isDesktop}>
                <div class="slds-box slds-theme_shade">
                    <h2>💻 Desktop Layout Active</h2>
                    <p>Displaying complex multi-column grids and high-density data here.</p>
                </div>
            </template>

            <!-- Tablet View -->
            <template lwc:elseif={isTablet}>
                <div class="slds-box slds-theme_shade">
                    <h2>📱 Tablet Layout Active</h2>
                    <p>Displaying touch-friendly buttons and medium-density data.</p>
                </div>
            </template>

            <!-- Mobile View -->
            <template lwc:elseif={isMobile}>
                <div class="slds-box slds-theme_shade">
                    <h2>📲 Mobile Layout Active</h2>
                    <p>Displaying a vertical stack of simplified cards for small screens.</p>
                </div>
            </template>

        </div>
    </lightning-card>
</template>

CSS Media Queries vs. Form Factor

You might be wondering: "Why do I need this if I can just use CSS Media Queries?"

360 Card: Which approach should I use?

• CSS Media Queries (@media): Use this when you only need to change how things look. For example, changing a font size, adjusting padding, or stacking two columns into one column.
• Form Factor (@salesforce/client/formFactor): Use this when you need to change what is loaded. If your desktop view requires downloading a massive JavaScript charting library, you don't want your mobile users wasting their data downloading it just to hide it with CSS display: none;. Form Factor completely removes the HTML from the DOM.

Core Takeaway: Combine the Form Factor module for structural, structural HTML changes, and CSS Media Queries for purely visual styling adjustments.

Conclusion

Building dynamic device layouts in LWC is remarkably simple when you use the tools Salesforce provides. By importing the formFactor module, you guarantee that your application will behave predictably whether the user is logging in from their office PC or checking records on the go via the Salesforce Mobile App.

Happy coding!