1 | # vue-content-loader
|
2 |
|
3 | [![NPM version](https://img.shields.io/npm/v/vue-content-loader.svg?style=flat)](https://npmjs.com/package/vue-content-loader) [![NPM downloads](https://img.shields.io/npm/dm/vue-content-loader.svg?style=flat)](https://npmjs.com/package/vue-content-loader) [![CircleCI](https://circleci.com/gh/egoist/vue-content-loader/tree/master.svg?style=shield)](https://circleci.com/gh/egoist/vue-content-loader/tree/master)
|
4 |
|
5 | SVG component to create placeholder loading, like Facebook cards loading.
|
6 |
|
7 | ![preview](https://user-images.githubusercontent.com/4838076/34308760-ec55df82-e735-11e7-843b-2e311fa7b7d0.gif)
|
8 |
|
9 | ## Features
|
10 |
|
11 | This is a Vue port for [react-content-loader](https://github.com/danilowoz/react-content-loader).
|
12 |
|
13 | - Completely customizable: you can change the colors, speed and sizes.
|
14 | - Create your own loading: use the [online tool](https://create-content-loader.now.sh/) to create your custom loader easily.
|
15 | - You can use it right now: there are a lot of presets already.
|
16 | - Performance:
|
17 | - Tree-shakable and highly optimized bundle.
|
18 | - Pure SVG, so it's works without any javascript, canvas, etc.
|
19 | - Pure functional components.
|
20 |
|
21 | ## Install
|
22 |
|
23 | ⚠️ **The latest version is compatible with Vue 3 only.** For Vue 2 & Nuxt 2, use `vue-content-loader@^0.2` instead.
|
24 |
|
25 | With npm:
|
26 |
|
27 | ```bash
|
28 | npm i vue-content-loader
|
29 | ```
|
30 |
|
31 | Or with yarn:
|
32 |
|
33 | ```bash
|
34 | yarn add vue-content-loader
|
35 | ```
|
36 |
|
37 | CDN: [UNPKG](https://unpkg.com/vue-content-loader/) | [jsDelivr](https://cdn.jsdelivr.net/npm/vue-content-loader/) (available as `window.contentLoaders`)
|
38 |
|
39 | ## Usage
|
40 |
|
41 | 👀👉 Demo: [CodeSandbox](https://codesandbox.io/s/vue-content-loader-igfyf?file=/src/App.vue)
|
42 |
|
43 | ```vue
|
44 | <template>
|
45 | <content-loader></content-loader>
|
46 | </template>
|
47 |
|
48 | <script>
|
49 | import { ContentLoader } from 'vue-content-loader'
|
50 |
|
51 | export default {
|
52 | components: {
|
53 | ContentLoader,
|
54 | },
|
55 | }
|
56 | </script>
|
57 | ```
|
58 |
|
59 | ### Built-in loaders
|
60 |
|
61 | ```js
|
62 | import {
|
63 | ContentLoader,
|
64 | FacebookLoader,
|
65 | CodeLoader,
|
66 | BulletListLoader,
|
67 | InstagramLoader,
|
68 | ListLoader,
|
69 | } from 'vue-content-loader'
|
70 | ```
|
71 |
|
72 | `ContentLoader` is a meta loader while other loaders are just higher-order components of it. By default `ContentLoader` only displays a simple rectangle, here's how you can use it to create custom loaders:
|
73 |
|
74 | ```vue
|
75 | <ContentLoader viewBox="0 0 250 110">
|
76 | <rect x="0" y="0" rx="3" ry="3" width="250" height="10" />
|
77 | <rect x="20" y="20" rx="3" ry="3" width="220" height="10" />
|
78 | <rect x="20" y="40" rx="3" ry="3" width="170" height="10" />
|
79 | <rect x="0" y="60" rx="3" ry="3" width="250" height="10" />
|
80 | <rect x="20" y="80" rx="3" ry="3" width="200" height="10" />
|
81 | <rect x="20" y="100" rx="3" ry="3" width="80" height="10" />
|
82 | </ContentLoader>
|
83 | ```
|
84 |
|
85 | This is also how [ListLoader](./src/ListLoader.js) is created.
|
86 |
|
87 | You can also use the [online tool](http://danilowoz.com/create-vue-content-loader/) to create shapes for your custom loader.
|
88 |
|
89 | ## API
|
90 |
|
91 | ### Props
|
92 |
|
93 | | Prop | Type | Default | Description |
|
94 | | ------------------- | -------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
95 | | width | number, string | | SVG width in pixels without unit |
|
96 | | height | number, string | | SVG height in pixels without unit |
|
97 | | viewBox | string | `'0 0 ${width ?? 400} ${height ?? 130}'` | See [SVG viewBox](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/viewBox) attribute |
|
98 | | preserveAspectRatio | string | `'xMidYMid meet'` | See [SVG preserveAspectRatio](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/preserveAspectRatio) attribute |
|
99 | | speed | number | `2` | Animation speed |
|
100 | | primaryColor | string | `'#f9f9f9'` | Background color |
|
101 | | secondaryColor | string | `'#ecebeb'` | Highlight color |
|
102 | | uniqueKey | string | `randomId()` | Unique ID, you need to make it consistent for SSR |
|
103 | | animate | boolean | `true` | |
|
104 | | baseUrl | string | empty string | Required if you're using `<base url="/" />` in your `<head />`. Defaults to an empty string. This prop is common used as: `<content-loader :base-url="$route.fullPath" />` which will fill the SVG attribute with the relative path. Related [#14](https://github.com/egoist/vue-content-loader/issues/14). |
|
105 | | primaryOpacity | number | `1` | Background opacity (0 = transparent, 1 = opaque) used to solve an issue in Safari |
|
106 | | secondaryOpacity | number | `1` | Background opacity (0 = transparent, 1 = opaque) used to solve an issue in Safari |
|
107 |
|
108 | ## Examples
|
109 |
|
110 | ### Responsiveness
|
111 |
|
112 | To create a responsive loader that will follow its parent container width, use only the `viewBox` attribute to set the ratio:
|
113 |
|
114 | ```vue
|
115 | <ContentLoader viewBox="0 0 300 200">
|
116 | <!-- ... -->
|
117 | </ContentLoader>
|
118 | ```
|
119 |
|
120 | To create a loader with fixed dimensions, use `width` and `height` attributes:
|
121 |
|
122 | ```vue
|
123 | <ContentLoader width="300" height="200">
|
124 | <!-- ... -->
|
125 | </ContentLoader>
|
126 | ```
|
127 |
|
128 | Note: the exact behavior might be different depending on the CSS you apply to SVG elements.
|
129 |
|
130 | ## Credits
|
131 |
|
132 | This is basically a Vue port for [react-content-loader](https://github.com/danilowoz/react-content-loader).
|
133 |
|
134 | [Thanks to @alidcastano for transferring the package name to me.](https://github.com/egoist/vue-content-loader/issues/1) 😘
|
135 |
|
136 | ## License
|
137 |
|
138 | MIT © [EGOIST](https://github.com/egoist)
|