Wondering what’s next for npm?Check out our public roadmap! »

    vue-screen
    TypeScript icon, indicating that this package has built-in type declarations

    1.5.4 • Public • Published

    npm version Build Status Build Status

    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

    - 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 currently not supported.

    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

    Data on support for the matchmedia feature across the major browsers from caniuse.com

    License

    MIT

    Install

    npm i vue-screen

    DownloadsWeekly Downloads

    6,198

    Version

    1.5.4

    License

    MIT

    Unpacked Size

    54.7 kB

    Total Files

    22

    Last publish

    Collaborators

    • avatar