feat: Add customizable highlight and animation to Skeleton

BrayamValero · BrayamValero · commit ca756f762b06 · 2025-06-24T12:19:31.000-04:00
- Introduces new props to Skeleton and SkeletonTheme components: baseColor, highlightColor, animationDirection, and customHighlightBackground, allowing for more flexible skeleton loading animations.

- Updates documentation to reflect these changes, revises styles to use CSS variables for color and animation, and bumps package version to 2.0.0 to indicate breaking or significant new features.
diff --git a/README.md b/README.md
@@ -138,7 +138,7 @@ Customize individual skeletons with props, or render a SkeletonTheme to style al
 <template>
     <div class="Home">
         <!-- This applies Base Color and Highligh Color to all Skeletons -->
-        <SkeletonTheme background-color="#303030">
+        <SkeletonTheme base-color="#303030" highlight-color="#606060">
             <h1>
                 <Skeleton>{{ data.title }}</Skeleton>
             </h1>
@@ -158,25 +158,42 @@ Down bellow you can take a look at each prop available.
 
 ### `<Skeleton>`
 
-| Name           | Type      | Description                                                          | Default |
-| -------------- | --------- | -------------------------------------------------------------------- | ------- |
-| rows           | `number`  | Set component amount of rows                                         | `1`     |
-| circle         | `boolean` | Set component `border-radius` to 50%, it replaces borderRadius props | `false` |
-| containerClass | `string`  | Set component class to skeleton container                            | `null`  |
-| childClass     | `string`  | Set component class to each skeleton child                           | `null`  |
+| Name           | Type      | Description                                                          | Default     |
+| -------------- | --------- | -------------------------------------------------------------------- | ----------- |
+| rows           | `number`  | Set component amount of rows                                         | `1`         |
+| circle         | `boolean` | Set component `border-radius` to 50%, it replaces borderRadius props | `false`     |
+| containerClass | `string`  | Set component class to skeleton container                            | `null`      |
+| childClass     | `string`  | Set component class to each skeleton child                           | `null`      |
 | loading        | `boolean` | Set component loading state                                          | `undefined` |
 
 ### `<Skeleton>` `<SkeletonTheme>`
 
-| Name              | Type              | Description                                                                                            | Default   |
-| ----------------- | ----------------- | ------------------------------------------------------------------------------------------------------ | --------- |
-| width             | `string` `number` | Set component `width`, it can be either number `px` or string with its corresponding css value         | `100%`    |
-| height            | `string` `number` | Set component `height`, it can be either number `px` or string with its corresponding css value        | `inherit` |
-| borderRadius      | `string` `number` | Set component `border-radius`, it can be either number `px` or string with its corresponding css value | `0.25rem` |
-| backgroundColor   | `string`          | Set component `background-color`                                                                       | `#e1e1e1` |
-| animationDuration | `number`          | Set component `animation-duration` in seconds                                                          | `2`       |
-| enableAnimation   | `boolean`         | Set component animation status `running` or `paused`                                                   | `true`    |
-| inline            | `boolean`         | Set component inline behavior                                                                          | `false`   |
+| Name                      | Type               | Description                                                                                                      | Default     |
+| ------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------- | ----------- |
+| width                     | `string` `number`  | Set component `width`, it can be either number `px` or string with its corresponding css value                   | `100%`      |
+| height                    | `string` `number`  | Set component `height`, it can be either number `px` or string with its corresponding css value                  | `inherit`   |
+| borderRadius              | `string` `number`  | Set component `border-radius`, it can be either number `px` or string with its corresponding css value           | `0.25rem`   |
+| baseColor                 | `string`           | Set component `background-color`                                                                                 | `#ebebeb`   |
+| highlightColor            | `string`           | Set component `background-image` highlight color animation                                                       | `#ebebeb`   |
+| animationDuration         | `number`           | Set component `animation-duration` in seconds                                                                    | `#f5f5f5`   |
+| animationDirection        | `normal` `reverse` | Set component animation direction `normal` (left to right) or `reverse` (right to left)                          | `normal`    |
+| enableAnimation           | `boolean`          | Set component animation status `running` or `paused`                                                             | `true`      |
+| inline                    | `boolean`          | Set component inline behavior                                                                                    | `false`     |
+| customHighlightBackground | `string`           | Override the `background-image` property of the highlight element, enabling you to fully customize the gradient. | `undefined` |
+
+#### Custom Highlight Background
+
+You may want to make the gradient used in the highlight element narrower or wider. To do this, you can set the
+customHighlightBackground prop. Here's an example of a narrow highlight:
+
+```html
+<Skeleton custom-highlight-background="linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%)">
+    Loading...
+</Skeleton>
+```
+
+If you use this prop, the baseColor and highlightColor props are ignored, but you can still reference their
+corresponding CSS variables as shown in the above example.
 
 ### Troubleshooting
 
diff --git a/package.json b/package.json
@@ -1,7 +1,7 @@
 {
     "name": "@brayamvalero/vue3-skeleton",
     "description": "An elegant skeleton library compatible with Vue 3",
-    "version": "1.0.1",
+    "version": "2.0.0",
     "author": "Brayam Valero",
     "license": "MIT",
     "repository": {
diff --git a/src/App.vue b/src/App.vue
@@ -45,7 +45,7 @@ onMounted(() => {
         <!-- User Profile example -->
         <section class="user">
             <picture class="user-avatar">
-                <Skeleton v-if="!data.img" childClass="user-avatar" background-color="#666" />
+                <Skeleton v-if="!data.img" childClass="user-avatar" />
                 <img v-else :src="data.img" />
             </picture>
             <div class="user-info">
@@ -64,7 +64,7 @@ onMounted(() => {
         <h2 class="mb-2">Inline loading with static data</h2>
         <section class="user">
             <picture class="user-avatar">
-                <Skeleton :loading="manualLoading" childClass="user-avatar" background-color="#666">
+                <Skeleton :loading="manualLoading" childClass="user-avatar">
                     <img :src="data.img" />
                 </Skeleton>
             </picture>
diff --git a/src/components/Skeleton.vue b/src/components/Skeleton.vue
@@ -7,7 +7,7 @@ const props = withDefaults(defineProps<SkeletonProps>(), {
     rows: 1,
     enableAnimation: undefined,
     inline: undefined,
-    loading: undefined
+    loading: undefined,
 })
 
 const theme = inject(ThemeInjection, {})
@@ -21,7 +21,7 @@ const slots: any = useSlots()
 
 const getLoadingStatus = computed<boolean>(() => {
     if (props.loading !== undefined) return !props.loading
-    
+
     if (slots.default) return slots.default()[0].children || false
 })
 
@@ -31,9 +31,12 @@ const getStyles = (): CSSProperties => {
     const width = props.width ?? theme.width ?? null
     const height = props.height ?? theme.height ?? null
     const borderRadius = props.borderRadius ?? theme.borderRadius ?? null
-    const backgroundColor = props.backgroundColor ?? theme.backgroundColor ?? null
+    const baseColor = props.baseColor ?? theme.baseColor ?? null
+    const highlightColor = props.highlightColor ?? theme.highlightColor ?? null
     const animationDuration = props.animationDuration ?? theme.animationDuration ?? null
+    const animationDirection = props.animationDirection ?? theme.animationDirection ?? 'normal'
     const enableAnimation = props.enableAnimation ?? theme.enableAnimation ?? null
+    const customHighlightBackground = props.customHighlightBackground ?? theme.customHighlightBackground ?? undefined
     const circle = props.circle
 
     // Convert Width
@@ -48,14 +51,19 @@ const getStyles = (): CSSProperties => {
     // Rounded Circle
     if (circle) style.borderRadius = '50%'
 
-    // Background Color
-    if (backgroundColor) style.backgroundColor = backgroundColor
-
-    // Animation Duration
-    if (animationDuration) style.animationDuration = `${animationDuration}s`
-
-    // Animation Play State
-    if (enableAnimation) style.animationPlayState = enableAnimation ? 'running' : 'paused'
+    // Set Custom CSS Variables based on props or theme
+    if (baseColor) style['--base-color'] = baseColor
+    if (highlightColor) style['--highlight-color'] = highlightColor
+    if (animationDuration) style['--animation-duration'] = `${animationDuration}s`
+    if (animationDirection) style['--animation-direction'] = animationDirection
+    if (enableAnimation !== undefined) {
+        style['--pseudo-element-display'] = 'block'
+    } else {
+        style['--pseudo-element-display'] = enableAnimation ? 'block' : 'none'
+    }
+    if (customHighlightBackground) {
+        style['--custom-highlight-background'] = customHighlightBackground
+    }
 
     return style
 }
@@ -81,22 +89,54 @@ function convertToPx(value: string | number | null, name: 'width' | 'height' | '
 </template>
 
 <style>
-@keyframes placeholder-glow {
-    50% {
-        opacity: 0.5;
+@keyframes loading-skeleton {
+    100% {
+        transform: translateX(100%);
     }
 }
 
 .skeleton-loading {
+    --base-color: #ebebeb;
+    --highlight-color: #f5f5f5;
+    --animation-duration: 1.5s;
+    --animation-direction: normal;
+    --pseudo-element-display: block;
+
+    background-color: var(--base-color);
     width: 100%;
-    height: inherit;
     border-radius: 0.25rem;
-    background-color: #e1e1e1;
     display: inline-flex;
     line-height: 1;
     position: relative;
     user-select: none;
     overflow: hidden;
-    animation: placeholder-glow 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+}
+
+.skeleton-loading::after {
+    content: ' ';
+    display: var(--pseudo-element-display);
+    position: absolute;
+    top: 0;
+    left: 0;
+    right: 0;
+    height: 100%;
+    background-repeat: no-repeat;
+    background-image: var(
+        --custom-highlight-background,
+        linear-gradient(90deg, var(--base-color) 0%, var(--highlight-color) 50%, var(--base-color) 100%)
+    );
+    transform: translateX(-100%);
+
+    animation-name: loading-skeleton;
+    animation-direction: var(--animation-direction);
+    animation-duration: var(--animation-duration);
+    animation-timing-function: ease-in-out;
+    animation-iteration-count: infinite;
+}
+
+@media (prefers-reduced-motion) {
+    .skeleton-loading {
+        --pseudo-element-display: block;
+    }
 }
 </style>
diff --git a/src/types/index.types.ts b/src/types/index.types.ts
@@ -3,10 +3,13 @@ export interface SkeletonThemeProps {
     width?: string | number
     height?: string | number
     borderRadius?: string | number
-    backgroundColor?: string
-    animationDuration?: number
     enableAnimation?: boolean
     inline?: boolean
+    baseColor?: string
+    highlightColor?: string
+    animationDuration?: number
+    animationDirection?: 'normal' | 'reverse'
+    customHighlightBackground?: string
 }
 
 // Exclusive Props from Skeleton

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@brayamvalero/vue3-skeleton",`
`3`	`3`	`"description": "An elegant skeleton library compatible with Vue 3",`
`4`		`- "version": "1.0.1",`
	`4`	`+ "version": "2.0.0",`
`5`	`5`	`"author": "Brayam Valero",`
`6`	`6`	`"license": "MIT",`
`7`	`7`	`"repository": {`