nuxt-viewport

Define custom viewports for your Nuxt️ project

Features

• ⚡️  Fast & Light with MatchMedia API ⚡️
• 🕶  Auto detects the device viewport from Cookie & User-Agent
• 👌  Zero configuration to start
• 👴️  Supports IE9+

Note
This version is Nuxt 3 & Nuxt Bridge only. For Nuxt 2 see 1.0.1

Quick Setup

1. Add nuxt-viewport dependency to your project

1npx nuxi@latest module add nuxt-viewport

2. Add nuxt-viewport to the modules section of nuxt.config.js

1{
2  modules: [
3    [
4      'nuxt-viewport', {
5        /* Viewport options */
6      }
7    ],
8  ]
9}

using top level options

1{
2  modules: [
3    'nuxt-viewport',
4  ],
5
6  viewport: {
7    /* Viewport options */
8  },
9}

Usage

1<script setup>
2import { useNuxtApp } from '#app'
3const { $viewport } = useNuxtApp()
4
5watch($viewport.breakpoint, (newBreakpoint, oldBreakpoint) => {
6  console.log('Breakpoint updated:', oldBreakpoint, '->', newBreakpoint)
7})
8</script>
9
10<template>
11  <div>
12    <div v-if="$viewport.isLessThan('tablet')">Should render only on mobile</div>
13    <div v-else>Current breakpoint: {{ $viewport.breakpoint }}</div>
14  </div>
15</template>

Usage with composable

1<script setup>
2const viewport = useViewport()
3
4watch(viewport.breakpoint, (newBreakpoint, oldBreakpoint) => {
5  console.log('Breakpoint updated:', oldBreakpoint, '->', newBreakpoint)
6})
7</script>
8
9<template>
10  <div>
11    <div v-if="viewport.isLessThan('tablet')">Should render only on mobile</div>
12    <div v-else>Current breakpoint: {{ viewport.breakpoint }}</div>
13  </div>
14</template>

Usage with "@nuxt/bridge"

1<script setup>
2const viewport = useViewport()
3
4watch(viewport.breakpoint, (newBreakpoint, oldBreakpoint) => {
5  console.log('Breakpoint updated:', oldBreakpoint, '->', newBreakpoint)
6})
7</script>
8
9<template>
10  <div>
11    <div v-if="viewport.isLessThan('tablet')">Should render only on mobile</div>
12    <div v-else>Current breakpoint: {{ $viewport.breakpoint }}</div>
13  </div>
14</template>

Configuration

breakpoints

• Type: Object

An object where the key is the name of the viewport, and the value is the viewport size.

cookie

• Type: Object

An object with options for cookie. See more https://www.npmjs.com/package/cookiejs#cookie-attributes

defaultBreakpoints

• Type: Object
• Detectable devices: bot, desktop, mobile, tablet, tv

An object where the key is the name of the detected device, and the value is the breakpoint key.

fallbackBreakpoint

• Type: String
• Default: viewport

The breakpoint key to be used, if the device was not detected.

feature

• Type: 'minWidth' | 'maxWidth'
• Default: 'minWidth'

CSS media feature.

Default configuration

1{
2  // ...
3  viewport: {
4    breakpoints: {
5      desktop: 1024,
6      desktopMedium: 1280,
7      desktopWide: 1600,
8
9      mobile: 320,
10      mobileMedium: 375,
11      mobileWide: 425,
12
13      tablet: 768,
14    },
15
16    cookie: {
17      expires: 365, // 365 days
18      name: 'viewport',
19      path: '/',
20      sameSite: 'Strict',
21      secure: true,
22    },
23
24    defaultBreakpoints: {
25      desktop: 'desktop',
26      mobile: 'mobile',
27      tablet: 'tablet',
28    },
29
30    fallbackBreakpoint: 'desktop',
31
32    feature: 'minWidth',
33  },
34  // ...
35}

Example configuration for Tailwind CSS

1{
2  // ...
3  viewport: {
4    breakpoints: {
5      xs: 320,
6      sm: 640,
7      md: 768,
8      lg: 1024,
9      xl: 1280,
10      '2xl': 1536,
11    },
12
13    defaultBreakpoints: {
14      desktop: 'lg',
15      mobile: 'xs',
16      tablet: 'md',
17    },
18
19    fallbackBreakpoint: 'lg'
20  },
21  // ...
22}

Per-page configuration

You can override the global configuration for specific pages using definePageMeta.

1<script setup>
2import { definePageMeta } from '#imports'
3
4definePageMeta({
5  viewport: {
6    breakpoints: {
7      desktop: 1024,
8      mobile: 320,
9      tablet: 768
10    },
11    cookie: {
12      name: 'viewport-per-page'
13    }
14    // Other fields will be inherited from the global configuration
15  }
16})
17</script>

API

viewport.breakpoint

• Type: String

Current breakpoint.

viewport.breakpointValue

• Type: Number

1// Example using defaults.
2
3viewport.breakpointValue('desktop') // Result: 1024.
4viewport.breakpointValue('tablet') // Result: 768.
5viewport.breakpointValue('mobile') // Result: 320.

viewport.isGreaterThan

• Type: Boolean

1// Example: viewport.breakpoint is "mobile".
2
3viewport.isGreaterThan('mobile') // Result: false.
4viewport.isGreaterThan('desktop') // Result: false.

viewport.isGreaterOrEquals

• Type: Boolean

1// Example: viewport.breakpoint is "mobile".
2
3viewport.isGreaterOrEquals('mobile') // Result: true.
4viewport.isGreaterOrEquals('desktop') // Result: false.

viewport.isLessThan

• Type: Boolean

1// Example: viewport.breakpoint is "desktop".
2
3viewport.isLessThan('desktopWide') // Result: true.
4viewport.isLessThan('mobile') // Result: false.

viewport.isLessOrEquals

• Type: Boolean

1// Example: viewport.breakpoint is "tablet".
2
3viewport.isLessOrEquals('tablet') // Result: true.
4viewport.isLessOrEquals('mobile') // Result: false.

viewport.match

• Type: Boolean

1// Example: viewport.breakpoint is "tablet".
2
3viewport.match('tablet') // Result: true.
4viewport.match('desktop') // Result: false.

viewport.matches

• Type: Boolean

1// Example: viewport.breakpoint is "mobileWide".
2
3viewport.matches('tablet', 'mobileWide') // Result: true.
4viewport.matches('mobile', 'tablet') // Result: false.

viewport.queries

• Type: Object

Object with generated media queries.

Contributing

You can contribute to this module online with CodeSandBox:

Or locally:

1. Clone this repository
2. Install dependencies using yarn install or npm install
3. Start development server using yarn dev or npm run dev

License

MIT License

Copyright (c) mvrlin mvrlin@pm.me