search

CodelyTV / vue-skeleton

A Vue 3 component to create loading skeletons quickly
4 stars 0 forks source link

readme

Vue Skeleton

Make beautiful, animated loading skeletons that automatically adapt to your app.

This is a Vue port for react-loading-skeleton

CI

Installation

# npm
npm install @antoniogiroz/vue-skeleton

Usage

<script setup lang="ts">
import { Skeleton } from '@antoniogiroz/vue-skeleton'
</script>

<template>
  <Skeleton /> // Simple, single-line loading skeleton
  <Skeleton :count="5" /> // Five-line loading skeleton
</template>

Principles

Adapts to the styles you have defined

The Skeleton component should be used directly in your components in place of content that is loading. While other libraries require you to meticulously craft a skeleton screen that matches the font size, line height, and margins of your content, the Skeleton component is automatically sized to the correct dimensions.

For example:

<script setup lang="ts">
import { Skeleton } from '@antoniogiroz/vue-skeleton'

const props = defineProps<{
  title?: string;
  body?: string;
}>()
</script>

<template>
  <div>
    <h1 v-if="props.title">
      {{ props.title }}
    </h1>
    <Skeleton v-else />

    <template v-if="props.body">
      {{ props.body }}
    </template>
    <Skeleton v-else :count="10" />
  </div>
</template>

...will produce correctly-sized skeletons for the heading and body without any further configuration.

This ensures the loading state remains up-to-date with any changes to your layout or typography.

Don't make dedicated skeleton screens

Instead, make components with built-in skeleton states.

This approach is beneficial because:

  1. It keeps styles in sync.
  2. Components should represent all possible states — loading included.
  3. It allows for more flexible loading patterns. In the blog post example above, it's possible to have the title load before the body, while having both pieces of content show loading skeletons at the right time.

Theming

Customize individual skeletons with props, or render a SkeletonTheme to style all skeletons below it in the Vue hierarchy:

<script setup lang="ts">
import { Skeleton, SkeletonTheme } from '@antoniogiroz/vue-skeleton'
</script>

<template>
  <SkeletonTheme base-color="#202020" highlight-color="#444">
    <p>
      <Skeleton count="{3}" />
    </p>
  </SkeletonTheme>
</template>

Props Reference

Skeleton only

Prop Description Default
count?: number The number of lines of skeletons to render. If count is a decimal number like 3.5, three full skeletons and one half-width skeleton will be rendered. 1
circle?: boolean Makes the skeleton circular by setting border-radius to 50%. false
className?: string A custom class name for the individual skeleton elements which is used alongside the default class, vue-skeleton.
style?: Vue.CSSProperties This is an escape hatch for advanced use cases and is not the preferred way to style the skeleton. Props (e.g. width, borderRadius) take priority over this style object.

Skeleton and SkeletonTheme

Prop Description Default
baseColor?: string The background color of the skeleton. #ebebeb
highlightColor?: string The highlight color in the skeleton animation. #f5f5f5
width?: string | number The width of the skeleton. 100%
height?: string | number The height of each skeleton line. The font size
borderRadius?: string | number The border radius of the skeleton. 0.25rem
inline?: boolean By default, a <br /> is inserted after each skeleton so that each skeleton gets its own line. When inline is true, no line breaks are inserted. false
duration?: string | number The length of the animation in seconds. 1.5
direction?: 'ltr' | 'rtl' The direction of the animation, either left-to-right or right-to-left. 'ltr'
noAnimate?: boolean Whether the animation should disabled. The skeleton will be a solid color when this is true. You could use this prop to stop the animation if an error occurs. false

Thanks

Thanks to the project which this component is based on: react-loading-skeleton