├── .gitignore
├── CHANGELOG.md
├── LICENSE
├── README.md
├── package-lock.json
├── package.json
├── rollup.config.js
├── src
└── index.ts
└── tsconfig.json
/.gitignore:
--------------------------------------------------------------------------------
1 | /node_modules
2 | /dist
--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
1 | ## 1.0.3
2 |
3 | * Fix incorrect condition
4 |
5 | ## 1.0.2
6 |
7 | * Fix missing scrollbar width on simple breakpoint setup
8 |
9 | ## 1.0.1
10 |
11 | * Simpler getter setup
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2019 Stanislav Lashmanov
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | **This library is no longer maintained. Please refer to [`vue-component-media-queries`](https://github.com/CyberAP/vue-component-media-queries) instead.**
2 |
3 |
4 | # Vue-provide-responsive
5 | A Vue plugin that provides responsive design helpers, based on breakpoints.
6 |
7 | [](https://www.npmjs.com/package/vue-provide-responsive)
8 |
9 | [Demo](https://codesandbox.io/s/magical-shockley-wc287)
10 |
11 | * **Performant**. All the data is retrieved in a single pass.
12 | * **Zero collisions**. Uses [Provide\Inject](https://vuejs.org/v2/api/index.html#provide-inject), accepts any string or a symbol as a provision name.
13 | * **[SSR\Nuxt Ready](#ssr)**. Has [fallback width](#defaultwidth) for server-side rendering.
14 | * **Easy setup**. Nothing is required, minimal breakpoint configuration.
15 | * **Fully customizable**. Execute any arbitrary code in the resize callback, [provide your own helpers\values](#beforeprovide), customize existing helpers.
16 | * **Human readable**. No manual equality checks, easy to understand helper names.
17 |
18 |
19 | ```html
20 |
21 |
22 |
{{title}}
23 |
24 |
25 |
26 |
27 |
28 |
29 |
30 |
31 |
32 |
43 | ```
44 |
45 | ## Usage
46 |
47 | Install from npm
48 |
49 | `npm i vue-provide-responsive`
50 |
51 | Activate the plugin inside your app:
52 |
53 | ```js
54 | import Vue from 'vue';
55 | import VueResponsiveProvide from 'vue-provide-responsive';
56 |
57 | Vue.use(VueResponsiveProvide, {
58 | breakpoints: {
59 | mobile: 768
60 | // will be converted to responsive.isMobile helper (works exactly like a computed)
61 | // will be true if the viewport width is less or equals 768 pixels
62 | }
63 | });
64 | ```
65 |
66 | Use responsive helpers in any of your components:
67 |
68 | ```html
69 |
70 |
71 |
Is Desktop
72 |
Is Mobile
73 |
Current width: {{ responsive.width }}px
74 |
75 |
76 |
77 |
90 | ```
91 |
92 | ## Plugin configuration
93 |
94 | ### **`breakpoints`**
95 |
96 | An object listing resolution breakpoints that would be converted into responsive helpers.
97 |
98 | Could be either a breakpoint value (`number`) or a breakpoint configuration: `{ value: number, ignoreScrollbar: boolean }`.
99 |
100 | 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`.
101 |
102 | ```js
103 | import Vue from 'vue';
104 | import VueProvideResponsive from 'vue-provide-responsive';
105 |
106 | Vue.use(VueProvideResponsive, {
107 | breakpoints: {
108 | mobile: 768,
109 | desktop: {
110 | value: 1024,
111 | ignoreScrollbar: true
112 | }
113 | }
114 | });
115 | ```
116 |
117 | #### breakpoint configuration
118 |
119 | * `value`
120 |
121 | **Type**: `number`
122 |
123 | Maximum width
124 |
125 | * `ignoreScrollbar`
126 |
127 | **Type**: `boolean`
128 |
129 | **Default**: `false`
130 |
131 | Controls whether scrollbar width should be included in the breakpoint calculation.
132 | If not set your breakpoint value would be substracted by the scrollbar width.
133 |
134 | Scrollbar width is always zero outside browser enviroment (SSR on nodejs for example).
135 |
136 |
137 | ### **`name`**
138 |
139 | **Type**: `string` or `symbol`
140 |
141 | **Default**: `responsive`
142 |
143 | Used as a provision name.
144 |
145 | ```js
146 | // constants.js
147 | export const RESPONSIVE_SYMBOL = Symbol();
148 | ```
149 |
150 | ```js
151 | import Vue from 'vue';
152 | import VueProvideResponsive from 'vue-provide-responsive';
153 | import { RESPONSIVE_SYMBOL } from 'constants.js';
154 |
155 | Vue.use(VueProvideResponsive, {
156 | name: RESPONSIVE_SYMBOL
157 | });
158 | ```
159 |
160 | ```html
161 |
173 | ```
174 |
175 | ### **`beforeProvide`**
176 |
177 | **Type**: `function`
178 |
179 | **Arguments**:
180 |
181 | * `responsive`: Non-reactive responsive object
182 |
183 | Callback to extend responsive object before it becomes reactive. Useful for adding your own helpers.
184 |
185 | ```js
186 | import Vue from 'vue';
187 | import VueProvideResponsive from 'vue-provide-responsive';
188 |
189 | Vue.use(VueProvideResponsive, {
190 | beforeProvide(responsive) {
191 | // to behave like a computed we define a getter: responsive.isSmallHeight
192 | // you can define a function if you want and call it explicitly: responsive.myFunc()
193 | Object.defineProperty(responsive, 'isSmallHeight', {
194 | configurable: true,
195 | enumerable: true,
196 | // will become reactive on the component's context
197 | get() {
198 | return this.height < 500;
199 | }
200 | })
201 | },
202 | });
203 | ```
204 |
205 | You could also use this to create reactive properties in advance.
206 |
207 | ```js
208 | import Vue from 'vue';
209 | import VueProvideResponsive from 'vue-provide-responsive';
210 |
211 | Vue.use(VueProvideResponsive, {
212 | beforeProvide(responsive) {
213 | // this will be useful if you want height to be reactive
214 | responsive.height = 0;
215 | },
216 | });
217 | ```
218 |
219 | ### **`onResize`**
220 |
221 | **Type**: `function`
222 |
223 | **Arguments**:
224 |
225 | * `event`: Resize UIEvent
226 | * `responsive`: Reactive responsive object
227 |
228 | Callback that's called on every resize event. Useful to update properties on the `responsive` object.
229 |
230 | ```js
231 | import Vue from 'vue';
232 | import VueProvideResponsive from 'vue-provide-responsive';
233 |
234 | Vue.use(VueProvideResponsive, {
235 | onResize(event, responsive) {
236 | Vue.set(responsive, 'height', window.innerHeight);
237 | }
238 | });
239 | ```
240 |
241 | If you defined `height` beforehand then you don't need `Vue.set`:
242 |
243 | ```js
244 | import Vue from 'vue';
245 | import VueProvideResponsive from 'vue-provide-responsive';
246 |
247 | Vue.use(VueProvideResponsive, {
248 | beforeProvide(responsive) {
249 | responsive.height = 0;
250 | },
251 | onResize(event, responsive) {
252 | responsive.height = window.innerHeight;
253 | }
254 | });
255 | ```
256 |
257 | ### **`defaultWidth`**
258 |
259 | **Type**: `number`
260 |
261 | **Default**: `1024`
262 |
263 | Width that will be used when `window` is not available.
264 | SRR support relies on that value, so you can control what the default width will be when the exact device is unkown.
265 |
266 | ```js
267 | import Vue from 'vue';
268 | import VueProvideResponsive from 'vue-provide-responsive';
269 |
270 | Vue.use(VueProvideResponsive, {
271 | breakpoints: {
272 | mobile: 768
273 | },
274 | defaultWidth: 768
275 | // responsive.isMobile will be true on SSR context
276 | });
277 | ```
278 |
279 | #### Predictive rendering
280 | Could also be used with a prediction tool to determine layout in SSR context.
281 |
282 | Nuxt.js example using [UAParser.js](https://github.com/faisalman/ua-parser-js):
283 |
284 | ```js
285 | // plugins/responsive.js
286 | import Vue from 'vue';
287 | import VueProvideResponsive from 'vue-provide-responsive';
288 |
289 | export default ({ req }) => {
290 |
291 | const breakpoints = {
292 | mobile: 768,
293 | tablet: 1024,
294 | }
295 |
296 | const devices = {
297 | wearable: breakpoints.mobile,
298 | mobile: breakpoints.mobile,
299 | tablet: breakpoints.tablet,
300 | }
301 |
302 | const config = {
303 | breakpoints,
304 | defaultWidth: 1920,
305 | }
306 |
307 | if (req) {
308 | const uaparser = require('ua-parser-js');
309 | const { device } = uaparser(req.headers['user-agent']);
310 | const width = devices[device.type];
311 | if (width) config.defaultWidth = width;
312 | }
313 |
314 | Vue.use({
315 | // forces plugin to install on every request
316 | install: VueProvideResponsive.install
317 | }, config);
318 | }
319 | ```
320 |
321 | ### **`ssr`**
322 |
323 | **Type**: `boolean`
324 |
325 | **Default**: `false`
326 |
327 | 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.
328 |
329 | ### **`window`**
330 |
331 | **Type**: `window` instance
332 |
333 | A `window` substitute, could be useful if you don't want to work with global window instance.
334 |
335 |
336 | ## Responsive object
337 |
338 | ### **`width`**
339 |
340 | **Type**: `number`
341 |
342 | Current viewport width, equals to `defaultWidth` outside browser context (for example in SSR).
343 |
344 | ```html
345 |
346 |