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.
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.
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,
breakpointsOrderis 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.
