Vue Skeleton Content Loader

Why skeletons?

The idea of this component is to make the process transparent and easier. So the main point is to integrate this component with other tooling processes, such as:

• Server-side rendering;
• Progressive rendering;
• Any other that you like :)

It's totally transparent for you and you can integrate it easily into your application, improving your user experience 🎉

• Demo
• Install
• Usage
• Development
• Contribute

Demo

Try out our demos on Stackblitz!

• Usage: animations, appearance, and themes
• User Card Component Loading simulation using Vue Skeleton Loader

Install

You can get it on NPM by installing the vue-skeleton-content-loader module as a project dependency.

npm install vue-skeleton-content-loader --save

Usage

Basic Usage - Local import

To use VueSkeletonContentLoader in your Vue application, you first need to import it into your component's script section.

// YourComponent.vue
<script setup lang="ts">
import { VueSkeletonContentLoader } from 'vue-skeleton-content-loader';
</script>

<template>
  <div class="item">
    <p>Circle Skeleton</p>
    <VueSkeletonContentLoader count="5" appearance="circle" />
  </div>
  <div class="item">
    <p>Line Skeleton</p>
    <VueSkeletonContentLoader count="5" appearance="line" />
  </div>
  <div class="item">
    <p>Square Skeleton</p>
    <VueSkeletonContentLoader count="5" appearance="square" />
  </div>
</template>

Global Registration - Component register via app boostrap file

For global availability across your application, you can register VueSkeletonContentLoader when you create your Vue app instance.

// main.ts or main.js
import { createApp } from 'vue';
import App from './App.vue';
// Note: import default export for global registration
import VueSkeletonContentLoader from 'vue-skeleton-content-loader';

const app = createApp(App);
// Register globally
app.component('VueSkeletonContentLoader', VueSkeletonContentLoader);
app.mount('#app');

After global registration, you can use <VueSkeletonContentLoader> directly in any component's template without explicit import.

Props

VueSkeletonContentLoader accepts several props to customize its behavior and appearance:

• count - default 1: Number of skeleton lines/shapes to render.
• animation - default progress: Defines the CSS animation. See Animations for options.
• appearance - default line: Defines the shape of the skeleton. See Appearance for options.
• theme - default null: An object containing CSS styles to apply to the skeleton. See Theming for details.
• size - default null: A number to be passed for the component if appearance is square. Uses pixel as default unit and accepts as number or number with px suffix. E.G: 40 or 40px
• loadingText - default Loading...: attribute that defines the text value for aria-valuetext attribute. Defaults to "Loading..."
• aria-label - default loading: you can add ariaLabel as input of the component to set a different value.

Appearance

You can also define which appearance you want to use in your skeleton loader by passing the options in your component via the :appearance prop.

Options

• '' - default: it will use it '' as appearance. At the end, it will render like a line;
• line: it will render like a line. This is the same behavior as passing an empty string;
• circle: it will use circle as appearance. Great for avatar skeletons, for example :);
• square: it will use square as appearance and render it appropriately. Great for cards and images, for example;
• custom-content: it will NOT add any appearance. Great for custom content, such as SVG, internal components and such. Although not rendering appearance, animation will be added unless component has animation="false" prop;

Animations

You can also define which CSS animation you want to use - even not use any, if it's the case - in your skeleton loader by passing the options in your component via the :animation prop.

Options

• "false"|false: it will disable the animation. Component will receive false as string when animation prop is not using binding;
• progress - default: it will use it progress as animation;
• progress-dark: it will use it progress-dark as animation. Recommended if your color schema is darken;
• pulse: it will use pulse as animation;
• pulse-dark: it will use it pulse-dark as animation. Recommended if your color schema is darken;

progress is the default animation, used as the single one previously. If you don't pass the animation attribute, it defaults to progress.

<template>
  <div class="item">
    <!-- Disables the animation -->
    <VueSkeletonContentLoader animation="false" />
    <VueSkeletonContentLoader :animation="false" />
    <!-- Disables the animation, but receiving boolean value from binding -->
    <!-- Via binding it can receive `false` (boolean), "false" (string), or any other animation type -->
    <VueSkeletonContentLoader :animation="classAttributeWithBooleanFalseValue" />
    <!-- Uses `progress` as animation -->
    <VueSkeletonContentLoader animation="progress" />
    <VueSkeletonContentLoader />
    <!-- Uses `pulse` as animation -->
    <VueSkeletonContentLoader animation="pulse" />
  </div>
</template>

You can check the code details in the Stackblitz Live Demo Link

Theming

You can also define different styles for the skeleton loader by passing an object with the css styles - in dashed case - into the component via the :theme prop.

<template>
  <!--
  If you need to change all the background wrapper
  you need to apply the style changes on the
  `vue-skeleton-content-loader` component wrapper
  -->

  <div style="background: #FF0001; padding: 10px;">
    <VueSkeletonContentLoader
      count="5"
      :theme="{
        'border-radius': '5px',
        height: '50px',
        'background-color': '#992929',
        border: '1px solid white'
      }"
    />
  </div>
</template>

The :theme prop now accepts the same configuration as Vue's v-bind:style directive. That means you can manage to use it like you're doing with the built-in directive, having a pleasant and beautiful experience.

<template>
  <!--
  Note that we are using a combination of styles inside theme object,
  having `height.px` receiving a number and `background-color` receiving a HEX Color
  -->
  <div style="background: #FF0001; padding: 10px;">
    <VueSkeletonContentLoader
      count="5"
      :theme="{
        'height': `50px`,
        'background-color': '#992929'
      }"
    />
  </div>
</template>

You should change the styles on the skeleton wrapper element in case you need to change the background color. You can check the code details in the Stackblitz Live Demo Link or check out a content load simulation in this Stackblitz Live Demo Link

Development

Run demo locally

1. This project uses Vite as base. That means you just need to run npm run dev and access the link http://localhost:3000 (or whatever port Vite assigns) in your browser.

Run tests

1. Run npm test to run tests. In case you want to test using watch, please use npm run tdd.

Contribute

For any type of contribution, please follow the instructions in CONTRIBUTING.md and read CODE_OF_CONDUCT.md and PUBLISHING_HOTFIX.md files.

Author

Wilson Mendes (willmendesneto)

• https://instagram.com/willmendesneto
• http://github.com/willmendesneto