@libs-ui/components-skeleton

Component hiển thị hiệu ứng loading (skeleton) cho các thành phần giao diện chưa có dữ liệu.

Giới thiệu

LibsUiComponentsSkeletonComponent là một standalone Angular component giúp tạo ra các khung xương (skeleton) loading với hiệu ứng shimmer. Component hỗ trợ cấu hình linh hoạt cho phép tạo ra các layout phức tạp như danh sách, lưới, hoặc thẻ bài viết.

Tính năng

• ✅ Hiệu ứng Shimmer Loading mượt mà
• ✅ Tính toán tự động số lượng items dựa trên height container
• ✅ Hỗ trợ cấu hình Layout phức tạp (Rows & Cols nested)
• ✅ Custom Styles & Classes cho từng phần tử
• ✅ Tối ưu hiệu năng với ChangeDetectionStrategy.OnPush

Khi nào sử dụng

• Khi đang tải dữ liệu từ API và muốn hiển thị cấu trúc trang trước.
• Thay thế cho loading spinner truyền thống để cải thiện trải nghiệm người dùng (Perceived Performance).
• Sử dụng trong các danh sách, bảng, hoặc chi tiết nội dung.

Cài đặt

# npm
npm install @libs-ui/components-skeleton

# yarn
yarn add @libs-ui/components-skeleton

Import

import { LibsUiComponentsSkeletonComponent } from '@libs-ui/components-skeleton';

@Component({
  standalone: true,
  imports: [LibsUiComponentsSkeletonComponent],
  // ...
})
export class YourComponent {}

Ví dụ

Basic (Tự động tính toán)

Component sẽ tự động tính toán số lượng dòng dựa trên chiều cao của container cha.

<div class="h-[200px] w-full">
  <libs_ui-components-skeleton />
</div>

Custom Layout (Card Example)

Cấu hình để tạo ra skeleton giống một card (Avatar + Text).

const cardConfig: ISkeletonConfig = {
  repeat: 1,
  rows: [
    {
      classRow: 'flex gap-4 p-4 border rounded shadow-sm',
      cols: [
        // Avatar Column
        {
          item: { classIncludeItem: 'w-12 h-12 rounded-full' },
        },
        // Text Column
        {
          classCol: 'flex-1 flex flex-col gap-2 justify-center',
          item: { classIncludeItem: 'h-4 w-3/4 rounded' },
          cols: [{ item: { classIncludeItem: 'h-3 w-1/2 rounded' } }],
        },
      ],
    },
  ],
};

<libs_ui-components-skeleton [config]="cardConfig" />

API

LibsUiComponentsSkeletonComponent

Selector: libs_ui-components-skeleton

Inputs

| Property | Type | Default | Description | | ---------- | ----------------- | ------- | ----------------------------- | | [config] | ISkeletonConfig | {} | Cấu hình layout cho skeleton. |

Interfaces

ISkeletonConfig

export interface ISkeletonConfig {
  repeat?: number; // Số lần lặp lại toàn bộ structure
  heightContainer?: number; // Chiều cao cố định cho mỗi block
  classRows?: string; // Class cho container của rows
  styleMarginBottom?: number; // Margin bottom giữa các items (px)
  rows?: Array<{
    repeat?: number; // Số lần lặp lại row
    classRow?: string; // Class cho row
    classRowLast?: string; // Class cho row cuối cùng
    item?: ISkeletonItem; // Config cho item trong row (nếu có)
    classCols?: string; // Class cho container của cols
    classColsLast?: string; // Class cho container cols cuối
    cols?: Array<{
      repeat?: number; // Số lần lặp lại col
      classCol?: string; // Class cho col
      classColLast?: string; // Class cho col cuối
      item?: ISkeletonItem; // Config cho item trong col
    }>;
  }>;
}

ISkeletonItem

interface ISkeletonItem {
  classIncludeItem?: string; // Class áp dụng trực tiếp lên skeleton div (bg, animation)
  classInclude?: string; // Class áp dụng lên wrapper của skeleton item
  class?: string; // (Legacy)
  styleDefault?: boolean; // Nếu true, thêm margin-bottom default (16px) trừ item cuối
}

Styling

Component sử dụng CSS Animation mo-skeleton-loading và linear-gradient background để tạo hiệu ứng shimmer. Mặc định skeleton sẽ fill size của container cha (w-full h-full).

Demo

npx nx serve core-ui

Truy cập: http://localhost:4500/skeleton