vue3-mq

Vue 3 MQ (Media Query)

Define your breakpoints and build responsive design semantically and declaratively in a mobile-first way with Vue 3.

Use with vue@^3.x.x

Not compatible with Vue 2. Use vue-mq if you require Vue 2 support.

Table of Contents

• Migration Guide
• Installation
• Usage
• Browser Support
• Support

Migration Guide from vue-mq

Filter

Since Vue 3 has dropped support for filters, the previous functionality has been removed.

SSR

Presently, support for SSR has been removed until it can be tested properly.

Demo

See https://vue3-mq.info for a demonstration and usage guide for Vue3-MQ.

Installation

Using NPM

npm install vue3-mq

Usage

1.) Add plugin to Vue

Define your custom breakpoints by passing breakpoints option. This let you name the breakpoints as you want

Eg:

{ phone: 500, tablet: 1200, other: Infinity }

{ small: 500, large: 1200, whatever: Infinity }

{ xs: 300, s: 500, m: 800, l: 1200, xl: Infinity }

import { createApp } from "vue";
import VueMq from "vue3-mq";

const app = createApp({});

app.use(VueMq, {
  breakpoints: { // default breakpoints - customise this
    xs: 576,
    sm: 768,
    md: 992,
    lg: 1200,
    xl: 1400,
    xxl: Infinity
  }
})

app.mount('#app');

2.) Use $mq global property

After installing the plugin every instance of Vue component is given access to a reactive $mq property. Its value will be a String which is the current breakpoint.

Eg: (with default breakpoints)

'sm' => 0 > screenWidth < 450

'md' => 450 >= screenWidth < 1250

'lg' => screenWidth >= 1250

<template>
  <div>{{ $mq }}</div>
</template>

3.) Use $mq with a computed property

The $mq property is fully reactive, so feel free to use it in a computed.

createApp({
  computed: {
    displayText() {
      return this.$mq === 'sm' ? 'I am small' : 'I am large'
    }
  },
  template: `
    <h1>{{displayText}}</h1>
  `,
})

4.) Update breakpoints

A function is available via Vue's provide method which allows you to dynamically change the breakpoints which are responded to. Simply inject it into any component where it's needed.

import { inject, onMounted } from "vue";

setup() {
    const updateBreakpoints = inject("updateBreakpoints");

    onMounted() {
      updateBreakpoints({
            xs: 576,
            sm: 768,
            md: 992,
            lg: 1200,
            xl: 1400,
            xxl: Infinity
        })
    }
}

5.) MqLayout component

In addition to $mq property this plugin provide a wrapper component to facilitate conditional rendering with media queries.

Usage:

<mq-layout mq="lg">
  <span> Display on lg </span>
</mq-layout>
<mq-layout mq="md+">
  <span> Display on md and larger </span>
</mq-layout>
<mq-layout :mq="['sm', 'lg']" tag="span">
  Display on sm and lg
</mq-layout>

Props

mq => required : [String,Array] - see below

tag => optional : String - sets the HTML tag to use for the rendered component (default 'div')

MQ prop: no modifier

Renders the component only on screens matching your mq value

<mq-layout mq="lg">
  <span> Display on lg </span>
</mq-layout>

MQ prop: plus modifier

Appending a + to your mq property will make the component render on that breakpoint and any above

<mq-layout mq="lg+" tag="span">I will render on large and above screen sizes</mq-layout>

MQ prop: minus modifier

Appending a - to your mq property will make the component render on that breakpoint and any below

<mq-layout mq="md-" tag="span">I will render on medium and below screen sizes</mq-layout>

MQ prop: range modifier

Placing a - between two breakpoints in your mq property will make the component render on any breakpoints in that range

<mq-layout mq="sm-lg">I will render on small, medium and large screen sizes</mq-layout>

MQ prop: array of breakpoints

Will render the component if the current screen size matches any of the breakpoints in the array. Remember that you'll need to precede the property with a : in your template.

<mq-layout :mq="['sm', 'lg']" tag="span">
  Display on sm and lg
</mq-layout>

Browser Support

Since Vue3 will never support Internet Explorer, this browser is not supported.

If your browser doesn't support the MatchMedia API, you will need to use a polyfill to add support:

Paul Irish: matchMedia polyfill

Bugs / Support

Please open an issue for support.