Mobile Detect
Lightweight mobile detection module based on the Mobile_Detect.php library, providing services, Twig functions, cache contexts, and condition plugins for detecting mobile devices, tablets, and platforms.
mobile_detect
Install
composer require 'drupal/mobile_detect:^4.0'
composer require 'drupal/mobile_detect:^3.0'
Overview
Mobile Detect is a lightweight mobile detection module that integrates the popular Mobile_Detect.php library into Drupal. It is designed to aid developers utilizing mobile-first and responsive design techniques who need to make slight changes for mobile and tablet users.
The module provides a comprehensive set of tools for device detection including a service that can be used programmatically, Twig functions for use in templates, cache contexts for proper caching based on device type, and condition plugins that can be used with blocks and other visibility settings.
Key capabilities include detecting whether a visitor is using a mobile device, tablet, or desktop, as well as identifying the operating system platform (iOS, Android). The module automatically adds CSS classes to the HTML element (is-mobile, is-tablet) for easy CSS-based responsive adjustments.
Features
- Provides the mobile_detect service wrapping the Detection\MobileDetect library for programmatic device detection
- Twig functions for template-based device detection: is_mobile(), is_tablet(), is_device(), is_ios(), is_android_os()
- Three cache contexts (mobile_detect_device_type, mobile_detect_is_mobile, mobile_detect_platform) for proper cache variation based on device characteristics
- Device type condition plugin for visibility settings supporting phone, tablet, and desktop detection
- Device platform condition plugin for visibility settings supporting Android and iOS detection
- Mobile Detect Status block for development and debugging purposes displaying current device detection results
- Automatic CSS classes (is-mobile, is-tablet) added to HTML element for CSS-based responsive design
- Integration with paragraphs module through cache context attachment
Use Cases
Show different content for mobile vs desktop users
Use the Device type condition plugin on blocks to show a simplified navigation menu for mobile users while displaying a full mega-menu for desktop users. Configure the block visibility to show only when the device is 'phone' or 'tablet'.
Display app store badges based on platform
Use the Device platform condition to show an App Store badge for iOS users and a Google Play badge for Android users. Create two blocks with the appropriate condition settings.
Responsive image loading in templates
Use the is_mobile() Twig function in templates to load lower resolution images for mobile users: {% if is_mobile() %}<img src="mobile-image.jpg">{% else %}<img src="desktop-image.jpg">{% endif %}
Programmatic device detection in custom modules
Inject or retrieve the mobile_detect service in custom code: $detect = \Drupal::service('mobile_detect'); if ($detect->isMobile()) { // Mobile-specific logic }
CSS-based responsive adjustments
Use the automatically added CSS classes (is-mobile, is-tablet) on the HTML element for CSS-based styling: html.is-mobile .sidebar { display: none; }
Panel/Layout variant selection
When using Panels for page variants, create a Tablet variant and a Mobile variant using the Device type condition. Place the Tablet variant before Mobile in the variant list since Mobile_Detect considers tablets as mobile devices.
Tips
- Mobile_Detect considers tablet devices as also being mobile devices. When using both tablet and mobile rules, always place tablet rules first to ensure tablets are properly identified.
- Use the Mobile Detect Status block during development to verify device detection is working correctly.
- For anonymous users requiring device-specific content, remember that Internal Page Cache must be disabled, which has performance implications.
- The cache contexts ensure Drupal properly caches separate versions for different device types - always include the appropriate cache context when using device detection in custom code.
Technical Details
Admin Pages 1
/admin/config/user-interface/mobile-detect
Configure Mobile Detect settings. Currently provides an experimental option to add the mobile_detect_is_mobile cache context to every page automatically.
Permissions 1
Hooks 4
hook_preprocess_html
Adds CSS classes 'is-mobile' and 'is-tablet' to the HTML element based on device detection. Also adds the mobile_detect_is_mobile cache context.
hook_preprocess_paragraph
Adds the mobile_detect_is_mobile cache context to all paragraphs for proper cache variation.
hook_page_attachments_alter
Conditionally adds the mobile_detect_is_mobile cache context to all pages when enabled in configuration.
hook_theme
Defines the mobile_detect_status_block theme hook for the status block template.
Troubleshooting 3
The Internal Page Cache module assumes all pages served to anonymous users are identical regardless of cache contexts. If you need to vary content for anonymous users based on device detection, you must disable the Internal Page Cache module.
Issues with the actual device detection logic should be directed to the Mobile_Detect library's GitHub issue queue, not the Drupal module issue queue.
Clear all caches after changing cache context settings. Ensure you're using the correct cache context for your use case (mobile_detect_device_type, mobile_detect_is_mobile, or mobile_detect_platform).
Security Notes 2
- The module has security coverage from the Drupal Security Team.
- Device detection is based on user agent strings which can be spoofed by clients - do not use for security-critical decisions.