MatchMedia component library for vue
npm install vue-component-media-queries
MatchMedia component library for Vue.
* 🍳 Tiny. Less than 1kb gzipped total size.
* 🌳 Tree-shakeable. Import only the necessary components right where you need them.
* 💡 Server Rendered. No hydration errors, thoroughly tested with Nuxt.js, supports predictive rendering.
* 💊 Versatile. Works both on a component level (inside ) or as an injected property (inside
2. Get components from the global VueComponentMediaQueries object:
`html`
#### Component-based (global matching)
The primary way to use this library is to match media queries in a root wrapping component (this is your App.vue or Layout.vue),
then get the results in a child component (could be on any level in the rendering tree).
In order to do this there are two components: and .
1. does the actual matching and provides values down the render tree. You should put this component in your App.vue or Layout.vue.
2. retrieves these values from the and exposes them to rendering context through scoped slots.
You should put this component where you have to actually use these media queries.
Here's a basic setup for this method:
1. Wrap your app in a and pass queries object to it.
`html`
2. In any part of your app that's within the use component to retrieve the results of media queries.
`html`
in the example above refers to the mobile: '(max-width: 760px)' media query result taken from the .
This result is reactive – when you resize the page it will update accordingly.
----
#### Component-based (single query matching)
You can also use without .query
In that case you'll have to pass a directly to instead and get the result from a matches slot prop.
`html
`
This method should be used for one-off media queries that are not referenced anywhere else in your app and would bloat your queries object otherwise.
----
#### Provide\Inject
Lastly, it's possible to have just and no components.
Provide\Inject pattern can be used to get media queries results in your methods, computeds or lifecycle hooks.
To get the provided media queries results you'll need to:
1. Repeat the first step setting up at the start of this section
2. Inject mediaQueries in your component:
`html`
#### Props
##### queries
Type: { [name]: string }
Required: yes
queries is an object where:
* key is a media query name that would be then used in scoped slot or in mediaQueries injection.
* value is a media query expression. (How to use Media Queries)
`js`
const queries = {
mobile: '(max-width: 760px)',
tablet: '(max-width: 1024px)',
desktop: '(min-width: 1024px)',
landscape: '(orientation: landscape)'
}
queries are best passed to via the $options object$options
because contents are static and so should be your media queries object.
`html
`
##### fallback
Type: string or string[]
A key or a list of queries keys that should return true when window.matchMedia is unavailable (node.js\nuxt.js for example).
`html`
{{ mobile }}
Multiple fallbacks:
`html`
:fallback="['mobile', 'landscape']"
>
##### ssr
Type: boolean
This prop switches between eager and immediate mode for matching.
* An immediate mode sets all the queries to match before your components render.
It ensures that components using media queries won't have to re-render after a first render due to data mismatch
(all media queries return false before matching, except those listed in fallback prop).fallback
* An eager mode allows for components to render with fallback values first (passed to prop) to avoid hydration errors.
`html`
:fallback="['mobile', 'landscape']"
ssr
>
Set this prop to true if you have a custom server side rendering.true
Nuxt.js users will have this set to by default.
##### wrapperTag
Type: string
Default: span
A wrapping tag that is used when a component has more than one child.
`html`
wrapper-tag="'div'"
>
#### Events
##### change:[name]
Type: MediaQueryListEvent
Arguments:
* matches – boolean. Represents media query result.media
* — string. Media query.EventTarget
* Rest of interface.
An even fired when a media query name result changes.name is a key of queries object passed to .
`html
:queries="$options.queries"
>
`
----
#### Props
##### query
Type: string, a media query.
Required: yes, when is not a descendant of .
A media query that needs to be matched in place. See usage section for an example.
##### fallback
Type: string
Sets matches value to true when used outside of browser context (same as for ).
`html`
{{ matches }}
##### ssr
Type: boolean
Same as for .
##### wrapperTag
Type: string
Default: span
A wrapping tag that is used when a component has more than one child.
`html`
#### Scoped Slots
##### default slot
Slot props: { [name]: boolean } or { matches: boolean }
Returns a record of media queries results from the .
`html`
{{ mobile }}
Or returns a matches slot prop if you pass a query prop.
`html`
{{ matches }}
#### Events
##### change
Type: MediaQueryListEvent
Arguments:
* matches – boolean. Represents media query result.media
* — string. Media query.EventTarget
* Rest of interface.
Triggers when a result from passed media query prop changes.
`html`
----
Type: { [name]: boolean }
A record with the results of . See Provide\Inject section for an example.
You can use user agent detection (also called browser sniffing) to make a guess which media queries should return true.
This is useful when you want to avoid layout shifts and unnecessary re-renders after a hydration.
To do so, we'll have to parse user agent on server side, set fallback values for and pass them back to the client.
Here's an example of using ua-parser-js to make a guess which device is sending a request in a default Nuxt.js layout:
`html
``