Vue-provide-reponsive
A Vue plugin that provides responsive design helpers, based on breakpoints.
- Performant. All the data is retrieved in a single pass.
- Zero collisions. Uses Provide\Inject, accepts any string or a symbol as a provision name.
- SSR\Nuxt Ready. Has fallback width for server-side rendering.
- Easy setup. Nothing is required, minimal breakpoint configuration.
- Fully customizable. Execute any arbitrary code in the resize callback, provide your own helpers\values, customize existing helpers.
- Human readable. No manual equality checks, easy to understand helper names.
{{title}}
Usage
Install from npm
npm i vue-provide-responsive
Activate the plugin inside your app:
;; Vue;
Use responsive helpers in any of your components:
Is Desktop Is Mobile Current width: {{ responsive.width }}px
Plugin configuration
breakpoints
An object listing resolution breakpoints that would be converted into responsive helpers.
Could be either a breakpoint value (number
) or a breakpoint configuration: { value: number, ignoreScrollbar: boolean }
.
Breakpoints are Media Query\CSS compliant, in the sence that they do not include scrollbar width. So in result your breakpoint value will be redued by the scrollbar width (they same way as Media Queries work). You can disable that behaviour with ingnoreScrollbar: true
.
;; Vue;
breakpoint configuration
-
value
Type:
number
Maximum width
-
ignoreScrollbar
Type:
boolean
Default:
false
Controls whether scrollbar width should be included in the breakpoint calculation. If not set your breakpoint value would be substracted by the scrollbar width.
Scrollbar width is always zero outside browser enviroment (SSR on nodejs for example).
name
Type: string
or symbol
Default: responsive
Used as a provision name.
// constants.jsconst RESPONSIVE_SYMBOL = Symbol;
;;; Vue;
beforeProvide
Type: function
Arguments:
responsive
: Non-reactive responsive object
Callback to extend responsive object before it becomes reactive. Useful for adding your own helpers.
;; Vue;
You could also use this to create reactive properties in advance.
;; Vue;
onResize
Type: function
Arguments:
event
: Resize UIEventresponsive
: Reactive responsive object
Callback that's called on every resize event. Useful to update properties on the responsive
object.
;; Vue;
If you defined height
beforehand then you don't need Vue.set
:
;; Vue;
defaultWidth
Type: number
Default: 1024
Width that will be used when window
is not available.
SRR support relies on that value, so you can control what the default width will be when the exact device is unkown.
;; Vue;
Predictive rendering
Could also be used with a prediction tool to determine layout in SSR context.
Nuxt.js example using UAParser.js:
// plugins/responsive.js;; { const breakpoints = mobile: 768 tablet: 1024 const devices = wearable: breakpointsmobile mobile: breakpointsmobile tablet: breakpointstablet const config = breakpoints defaultWidth: 1920 if req const uaparser = ; const device = ; const width = devicesdevicetype; if width configdefaultWidth = width; Vue;}
ssr
Type: boolean
Triggers supports for hydration on the client. Set this to true
if you're using a custom SSR. Nuxt users will get this out of the box.
window
Type: window
instance
A window
substitute, could be useful if you don't want to work with global window instance.
Responsive object
width
Type: number
Current viewport width, equals to defaultWidth
outside browser context (for example in SSR).
Your screen width is higher than 500.
is%Breakpoint%
Type: boolean
Reactive helper based on breakpoint value.
;; Vue;
Your viewport width is less than 768 px minus scrollbar width.
Performance
resize
is usually not a frequent event, but in case you have a lot of heavy resize handling in your app you could use debounce
to reduce performance strain in your watchers or computeds.
Typescript support
You would need to declare typings yourself, since they can not be determined beforehand.
// main.ts or plugin.tsdeclare