DOCSEARCHbyAlgolia
Submit Docs

Nuxt Device

repository·main·Indexed 21 days ago

https://github.com/nuxt-modules/device

A Nuxt module for detecting device types (mobile, tablet, desktop), operating systems, browsers, and crawlers. It provides the $device helper and useDevice() composable to access detection flags, supports Amazon CloudFront and Cloudflare headers, and includes a configurable defaultUserAgent for static site generation.

Tokens
1.5K
Snippets
7
Records
11
Agent score
77%

What's inside @nuxtjs/device

  2. Amazon CloudFront support

    main

    When the user agent is Amazon CloudFront, the module automatically checks for specific CloudFront device headers instead of the standard user agent string:

    • CloudFront-Is-Android-Viewer
    • CloudFront-Is-Desktop-Viewer
    • CloudFront-Is-IOS-Viewer
    • CloudFront-Is-Mobile-Viewer
    • CloudFront-Is-Tablet-Viewer
    CAUTION

    The $device.isWindows and $device.isMacOS flags are not available when using Amazon CloudFront.

  4. Configure `defaultUserAgent`

    main

    The defaultUserAgent option allows you to set a fallback value for the user-agent header. This is particularly useful when running npm run generate (Static Site Generation) to ensure the crawler/generator simulates a specific device.

    Default value: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/64.0.3282.39 Safari/537.36

  5. Change Nuxt layouts dynamically based on device

    main

    To switch layouts based on the device type, disable the default layout in definePageMeta and use the $device helper within a <NuxtLayout> component.

    <template>
  <NuxtLayout :name="$device.isMobile ? 'mobile' : 'default'">
    <!-- page content -->
  </NuxtLayout>
</template>

<script setup>
definePageMeta({
  layout: false
})
</script>

  6. Use device detection in templates and scripts

    main

    You can access device information in two ways:

    1. In Templates: Use the $device helper directly.
    2. In Script Setup: Use the useDevice() composable to destructure specific properties.
    <template>
  <div>
    <div v-if="$device.isDesktop">Desktop</div>
    <div v-else-if="$device.isTablet">Tablet</div>
    <div v-else>Mobile</div>
  </div>
</template>

<script setup>
const { isMobile } = useDevice()
</script>
    <template>
  <div>
    <div v-if="$device.isDesktop">Desktop</div>

    <div v-else-if="$device.isTablet">Tablet</div>

    <div v-else>Mobile</div>
  </div>
</template>

<script setup>
const { isMobile } = useDevice()
</script>

  7. Configure the `defaultUserAgent` option

    main

    The defaultUserAgent option allows you to set a fallback user-agent header. This is particularly useful during static site generation (npm run generate) to ensure the device detection logic has a consistent user agent to parse when no real browser header is present.

    Defaults to: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/64.0.3282.39 Safari/537.36'

    export interface ModuleOptions {
  defaultUserAgent?: string
}

  8. Device detection flags and properties

    main

    The module provides several flags via the $device helper to detect device types, operating systems, browsers, and crawlers. It also injects the raw userAgent string.

    Device Types

    • $device.isDesktop
    • $device.isMobile
    • $device.isTablet
    • $device.isMobileOrTablet
    • $device.isDesktopOrTablet

    Operating Systems & Hardware

    • $device.isIos
    • $device.isLinux
    • $device.isWindows
    • $device.isMacOS
    • $device.isApple
    • $device.isAndroid
    • $device.isSamsung

    Browsers

    • $device.isFirefox
    • $device.isEdge
    • $device.isChrome
    • $device.isSafari

    Others

    • $device.isCrawler (powered by crawler-user-agents)
    • $device.userAgent (the raw user agent string)

  9. Access the $device object in Nuxt and Vue

    main

    The @nuxtjs/device module injects the $device object into your application. You can access it via the Nuxt app instance or directly within Vue components using the following interfaces:

    • In Nuxt App: Available on nuxtApp.$device.
    • In Vue Components: Available via this.$device (or via injection/provide patterns).
    // Accessing via NuxtApp
const { $device } = useNuxtApp()
if ($device.isMobile) { /* ... */ }

// Accessing in a Vue component
export default {
  mounted() {
    console.log(this.$device.isDesktop)
  }
}

  10. The Device type definition

    main

    The Device type defines the structure of the device detection object available in your Nuxt application. It contains boolean flags for detecting operating systems, browsers, device categories, and more, as well as the raw userAgent string.

    export type Device = {
  userAgent: string
  isDesktop: boolean
  isIos: boolean
  isAndroid: boolean
  isMobile: boolean
  isMobileOrTablet: boolean
  isDesktopOrTablet: boolean
  isTablet: boolean
  isLinux: boolean
  isWindows: boolean
  isMacOS: boolean
  isApple: boolean
  isSafari: boolean
  isFirefox: boolean
  isEdge: boolean
  isChrome: boolean
  isSamsung: boolean
  isCrawler: boolean
}

  11. Access device detection properties with useDevice()

    main

    Use the useDevice composable within your Nuxt components (e.g., in <script setup>) to access the device detection object. This object provides information about the current user's device, such as whether they are on a mobile, tablet, or desktop platform.

    The composable returns an object conforming to the Device type, which is attached to the Nuxt app instance as $device.

    <script setup>
const device = useDevice();

if (device.isMobile) {
  // Handle mobile specific logic
}
</script>