Installation

Setup

Add to Your Project

1. Install the unplugin-gueleton package

   npm

   npm install unplugin-gueleton@latest

   pnpm

   pnpm add unplugin-gueleton@latest

   yarn

   yarn add unplugin-gueleton@latest

2. Add unplugin-gueleton as a plugin to your build tool configuration

   vite.config.ts

   import { defineConfig } from 'vite'
   import Gueleton from 'unplugin-gueleton/vite'
   
   // https://vite.dev/config/
   export default defineConfig({
     plugins: [Gueleton()],
   })

   vite-plugin-html Notice

   When using with the vite-plugin-html plugin, you need to add the unplugin-gueleton plugin before vite-plugin-html to ensure proper HTML file processing.

   webpack.config.js

   const { Gueleton } = require('unplugin-gueleton/webpack')
   
   module.exports = {
     /* ... */
     plugins: [
       Gueleton(),
     ],
   }

   nuxt.config.ts

   // https://nuxt.com/docs/api/configuration/nuxt-config
   export default defineNuxtConfig({
     // ...
     modules: ['unplugin-gueleton/nuxt'],
     // ...
   })

   vue.config.js

   const { defineConfig } = require('@vue/cli-service')
   const { Gueleton } = require('unplugin-gueleton/webpack')
   
   module.exports = defineConfig({
     configureWebpack: {
       plugins: [
         Gueleton()
       ]
     }
   })

3. Register Gueleton components in your application

   main.ts

   import { createApp } from 'vue'
   import App from './App.vue'
   
   import GueletonPlugin from 'unplugin-gueleton/vue'
   
   createApp(App)
     .use(GueletonPlugin)
     .mount('#app')

   main.js

   import { createApp } from 'vue'
   import App from './App.vue'
   
   import GueletonPlugin from 'unplugin-gueleton/vue'
   
   createApp(App)
     .use(GueletonPlugin)
     .mount('#app')

   Tip

   Thanks to Nuxt’s auto-import feature, you don’t need to manually register components. Just make sure the plugin is properly configured in nuxt.config.ts.

   main.js

   import { createApp } from 'vue'
   import App from './App.vue'
   
   import GueletonPlugin from 'unplugin-gueleton/vue'
   
   createApp(App)
     .use(GueletonPlugin)
     .mount('#app')

4. Start the development server

   Gueleton 会向 Nuxt 开发服务器添加一个新的路由 /__gueleton/，用于访问 Gueleton 的管理面板。

   成功启动后，Gueleton 会在控制台打印一条消息，提示你可以访问的 URL。

   Nuxt 4.0.3 with Nitro 2.12.4                                                                                                     nuxi 16:22:59
                                                                                                                                         16:22:59
     ➜ Local:    http://localhost:3000/
     ➜ Network:  use --host to expose
   
     ➜ DevTools: press Shift + Option + D in the browser (v2.6.3)                                                                        16:23:00
   
   ℹ ➜  Gueleton: http://localhost:3000/__gueleton/                                                                       nuxt-gueleton 16:23:02

   Gueleton 会 启动一个服务器，用于访问 Gueleton 的管理面板。

   成功启动 webpack 开发服务器后，Gueleton 会在控制台打印一条消息，提示你可以访问的 URL。

     - Local:   http://localhost:8080/
     - Network: http://192.168.224.65:8080/
   
   ➜  Gueleton: http://localhost:5679/__gueleton/

   Gueleton 会向 Vite 开发服务器添加一个新的路由 /__gueleton/，用于访问 Gueleton 的管理面板。

   成功启动后，Gueleton 会在控制台打印一条消息，提示你可以访问的 URL。

     VITE v7.1.3  ready in 666 ms
   
     ➜  Local:   http://localhost:5173/
     ➜  Network: use --host to expose
     ➜  press h + enter to show help
     ➜  Gueleton: http://localhost:5173/__gueleton/

   Gueleton 会 启动一个服务器，用于访问 Gueleton 的管理面板。

   成功启动开发服务器后，Gueleton 会在控制台打印一条消息，提示你可以访问的 URL。

     - Local:   http://localhost:8080/
     - Network: http://192.168.224.65:8080/
   
   ➜  Gueleton: http://localhost:5679/__gueleton/

   

5. Finally, you need to understand some Gueleton specific concepts.

   Skeleton placeholders are generally composed of a light background with one or more dark blocks.

   container

   bone

   bone

   bone

   Gueleton calls the light background container, and the dark blocks bone.

   When customizing skeleton placeholder styles, you’ll use them to define the background and skeleton block styles respectively.

   That’s it! Now you’ve successfully installed Gueleton and can start using it to add skeleton placeholders to your application.

Options

You can customize global Gueleton behavior by passing options to the plugin.

limit

Use the limit option to set cropping rules for pre-stored data. It can be a number or an object.

• When limit is a number, it represents taking the first limit items, only valid for arrays.

• When limit is an object, length represents taking the first length items, properties represents cropping object properties, only valid for objects.

• Default value: 3

main.ts

import { createApp } from 'vue'
import App from './App.vue'

import { GueletonPlugin, GueletonProvider } from 'unplugin-gueleton/vue'

GueletonProvider.updateOptions({
  // limit: 3,
  limit: { length: 3, properties: ['id', 'name'] },
})

createApp(App)
  .use(GueletonPlugin)
  .mount('#app')

main.js

import { createApp } from 'vue'
import App from './App.vue'

import { GueletonPlugin, GueletonProvider } from 'unplugin-gueleton/vue'

GueletonProvider.updateOptions({
  // limit: 3,
  limit: { length: 3, properties: ['id', 'name'] },
})

createApp(App)
  .use(GueletonPlugin)
  .mount('#app')

app.config.ts

export default defineAppConfig({
  gueleton: {
    // limit: 3,
    limit: { length: 3, properties: ['id', 'name'] },
  }
})

main.js

import { createApp } from 'vue'
import App from './App.vue'

import { GueletonPlugin, GueletonProvider } from 'unplugin-gueleton/vue'

GueletonProvider.updateOptions({
  // limit: 3,
  limit: { length: 3, properties: ['id', 'name'] },
})

createApp(App)
  .use(GueletonPlugin)
  .mount('#app')

fuzzy

Use the fuzzy option to adjust how Gueleton determines which DOM elements are recognized as bone.

Lower fuzzy values generate more, finer-grained skeleton blocks, while higher values generate fewer, larger blocks. This is also key to how Gueleton automatically adapts to different UI component libraries.

• Default value: 1
• Examples:

  1. When fuzzy is set to 1, p1 and span1 are recognized as bone respectively.

     <div class="div1">
       <p class="p1">This is a paragraph.</p>
       <p class="p2">
         <span class="span1">Inline element</span>
       </p>
     </div>

  2. When fuzzy is set to 2, the entire div1 will be recognized as one bone.

     <div class="div1">
       <p class="p1">This is a paragraph.</p>
       <p class="p2">
         <span class="span1">Inline element</span>
       </p>
     </div>

Tip

Check out the fuzzy example to better understand the fuzzy mechanism.

type

Use the type option to set how skeletons are rendered.

• Options:
  • overlay (default): The entire skeleton placeholder will overlay the actual content.
  • inPlace: bone will overlay its parent element.

bone and container

Use bone and container options to customize bone and container styles respectively.

Both can accept a style object and className string.

bone

• Default value:

  {
    style: {
      backgroundColor: 'rgba(240, 240, 240, 1)',
    },
    className: '',
  }

container

• Default value:

  {
    style: {
      cursor: 'wait',
      backgroundColor: 'rgba(255, 255, 255, 1)',
    },
    className: '',
    leave: {}
  }

container.leave

When data loading is complete, Gueleton removes the skeleton placeholder and displays the actual content. The container.leave option allows you to define leaving styles for the container element. Combined with the transition property, it can achieve smoother transition effects.

The transition animation example shows how to implement skeleton fade-out effects by modifying leave styles.

• Default value:

  {
    style: {},
    className: '',
  }