vue-screen

VueScreen

Reactive window size and media query states for VueJS. Supports your favourite UI framework grid breakpoints out of the box, and can be configured with any custom breakpoints.

Demo

Table of contents

• Features
• Requirements
• Installation
• Setup
• Basic usage
  • In a template
  • As computed properties
  • As watchers
• Configuration
  • Breakpoints
    • Default breakpoints
      • Tailwind (default)
      • Bootstrap
      • Bulma
      • Foundation
      • Materialize
      • Semantic UI
    • Custom breakpoints
  • Callbacks
  • Breakpoints order
• API
  • Width
  • Height
  • Touch
  • Portrait
  • Landscape
  • Breakpoint
  • Config
  • <breakpoint key>
  • <callback key>
• Nuxt module
• SSR Caveats
• Browser support
• License

Features

✅ - Reactive and debounced window innerWidth and innerHeight
✅ - Reactive media query states and device orientation
✅ - Detect touch screen capability
✅ - Breakpoints for most common ui frameworks provided out of the box: Tailwind, Bootstrap, Bulma, Foundation, Materialize, Semantic UI
✅ - SSR compatible with Nuxt module included

Requirements

As the library uses Vue.Observable API internally, Vue 2.6+ is required.
Vue 3 is supported on the @next tag. More info

Installation

Embed directly as a script:

<script src="https://unpkg.com/vue-screen/dist/vue-screen.min.js"></script>

When embedding, the script automatically registers itself as a Vue plugin.

Via npm:

npm i vue-screen

Via yarn:

yarn add vue-screen

Setup

import Vue from 'vue';
import VueScreen from 'vue-screen';

Vue.use(VueScreen);

Basic usage

After registering, the property $screen will be injected on the Vue prototype. You can access it in a component using this.$screen.

In a template

<template>
    <div>
        <p>Page width is {{ $screen.width }} px</p>
        <p>Page height is {{ $screen.height }} px</p>
        <p>Current breakpoint is {{ $screen.breakpoint }} px</p>
    </div>
</template>

As computed properties

<template>
    <div :class="media">
        <p>VueScreen</p>
    </div>
</template>
<script>
export default {
    computed: {
        media() {
            return {
                'is-phone': this.$screen.sm,
                'is-tablet': this.$screen.md,
                'is-desktop': this.$screen.lg,
                'can-touch': this.$screen.touch,
                'breakpoint': this.$screen.breakpoint,
            };
        }
    }
}
</script>

As watchers

export default {
    watch: {
        '$screen.width'() {
            alert('Width changed');
        }
    }
}

Check out demo source code for more examples.

Configuration

Breakpoints

Default breakpoints

Use default breakpoints from one of the supported UI frameworks:

Tailwind (default)

Vue.use(VueScreen); 

Vue.use(VueScreen, 'tailwind'); 

Bootstrap

Vue.use(VueScreen, 'bootstrap'); 

Bulma

Vue.use(VueScreen, 'bulma'); 

Foundation

Vue.use(VueScreen, 'foundation'); 

Materialize

Vue.use(VueScreen, 'materialize'); 

Semantic UI

Vue.use(VueScreen, 'semantic-ui'); 

Custom breakpoints:

Vue.use(VueScreen, {
    sm: 480, // will be converted to 480px
    md: '47em',
    lg: '1200px',
}); 

You can find default UI framework breakpoints here

Callbacks

You can provide callbacks to decorate the $screen object with custom properties. They are similar to Vue computed properties, but they can only depend on the properties of the $screen object will be run every time the debounced window resize event is triggered

Vue.use(VueScreen, {
    md: 768,
    lg: 992,
    xl: 1200,
    tablet: screen => screen.md && !screen.xl && screen.touch,
});

Callbacks results will be included in the $screen object along with other breakpoint properties.

console.log(this.$screen)
/*
Output on an iPad in portrait mode:
{
    md: true,
    lg: true,
    xl: false
    tablet: true,
}
*/

To use callbacks together with breakpoints from one of the supported UI frameworks you can specify the extend property:

Vue.use(VueScreen, {
    extend: 'bootstrap',
    tablet: screen => screen.md && !screen.xl && screen.touch,
});

Breakpoints order

This property is required in order to make $object.breakpoint property work with custom breakpoint names.
Example:

Vue.use(VueScreen, {
    phonePortrait: 0,
    phoneLandscape: 520,
    tabletPortrait: 768,
    tabletLandscape: 1024,
    desktop: 1200,
    breakpointsOrder: ['phonePortrait', 'phoneLandscape', 'tabletPortrait', 'tabletLandscape', 'desktop']
});

If you extend one of the default frameworks, breakpointsOrder is provided automatically.

API

Available properties on the $screen object:

width

Number
Alias of window.innerWidth

height

Number
Alias of window.innerHeight

touch

Boolean
Tells if touch events are supported

portrait

Boolean
Tells if the device is in portrait mode

landscape

Boolean
Tells if the device is in landscape mode

breakpoint

String
Returns the currently active breakpoint. If you use custom breakpoint names, you must provide the breakpointsOrder property.

config

Object
Access the configuration passed when registering the plugin.

<breakpoint key>

Boolean
Every breakpoint key specified in the configuration will be available as a boolean value indicating if the corresponding media query matches.

To view default breakpoint keys and values for each framework, click here.

<callback key>

Any
Every callback specified in the configuration will have a corresponding property indicating the result of the callback. Callbacks will be called on every debounced resize event.

Nuxt module

The library can be used directly as a Nuxt module, just add it to the module section in nuxt.config.js:

export default {
    ...
    ...
    modules: [
        'vue-screen/nuxt',
    ],

    screen: {
        extend: 'bootstrap',
    },
    ...
    ...
}

SSR caveats

While this library has no problems with SSR, there are some caveats related to the fact that when performing SSR the server does not have a screen size. Due to this, when performing SSR this library will always have a $screen object with the following properties:

{
    width: 410,
    height: 730,
    touch: true,
    portrait: true,
    landscape: false,
    breakpoint: '<first breakpoint returned by breakpointsOrder>',
}

These values are some sensible defaults to promote a mobile-first approach.


This behavior however can lead to hydration errors if you wanna conditionally render a component based on one of the $screen properties:

<template>
    <div>
        <MyComponent v-if="$screen.lg" />
    </div>
</template>

When performing SSR, the template will be compiled into <div><!----></div>.
When rendering the component on a browser with a width that matches the $screen.lg condition, the template will be compiled into <div><MyComponent /></div>.
This will make Vue generate a warning in the console.

To read more about this topic you can check out this issue.

Browser support

All browsers that support matchMedia API

License

MIT