---
title: Skeleton Screen Usage Guide
---

# Skeleton Screen Usage Guide

<Callout type="info" emoji="ℹ️">
  The skeleton screen effectively reduces the initial page or page switching white screen time and improves visual continuity and loading experience.
</Callout>

## Applicable Scenarios

- Pages where the first screen has a lot of data and API responses have certain latency.
- Page switching shows obvious blank or flashing; want a more natural transition.
- Need placeholder display linked with Light / Dark theme.

## Requirements

- Base library version `>=2.27.2`
- @ray-js/cli version `>=1.6.30`
- Developer tool (IDE) version `>=0.9.0`

## Basic Workflow

### Step 1: Generate snapshot skeleton code in IDE

1. Open the skeleton preview tool in IDE.

<Image src="/images/skeleton/image5.png" />
2. Adjust parameters until satisfied then click "Copy Code".

#### Parameter Description
- Element Range: identifies page node hierarchy and controls generation scope.
- Ignore Element Size: filters very small elements to avoid meaningless placeholders.
- Extract Text Elements: converts text into unified styled placeholder blocks for consistent look.
- Ignore Inline Elements: excludes inline elements with uncertain width/height to avoid misalignment.
- Snapshot Background Color: configure background placeholder colors for light / dark theme.
- Custom Navigation Bar: if page uses `navigationStyle = custom`, check this to adapt the nav height offset.
- Keep Native Style: use the element's own background color as placeholder (otherwise unified skeleton color).
- Overlay Opacity: adjusts depth effect after stacking color blocks.

### Step 2: Create the skeleton snapshot file

Create a `pageName.snapshot.html` file under the corresponding page folder and paste the copied code from Step 1.

Directory Example:

```bash
└── home
    ├── index.config.ts
    ├── index.moudle.less
    ├── index.snapshot.html  # skeleton screen file
    └── index.tsx
```

<Image src="/images/skeleton/image2.png" width="260px" /> {/* Directory screenshot after file creation */}

### Step 3: Build & Verify

Execute the normal build process. In the output directory `dist` check whether the corresponding page contains `*.snapshot.html`:

<Image src="/images/skeleton/image3.png" width="260px" /> {/* dist directory output screenshot */}

Open the MiniApp page: before business logic and real content render, the skeleton placeholder layer should appear first and then naturally transition to real content.

## Skeleton Template Example

```html
<style data-version="v2" data-remove-type="default">
  [is="snapshot-root"] {
    pointer-events: none;
    z-index: 100000;
    position: fixed;
    top: 0;
    left: 0;
    width: 100vw;
    height: 130vh;
    background-color: var(--skeleton-bg);
  }
  [is="snapshot-root"] div {
    position: absolute;
  }
  /* Additional custom styles can be appended as needed */
</style>
<div style="top: 20px; width: 20vw; height: 20vh; background-color: #eee;">
  Skeleton Element
</div>
```

### Dark Theme Adaptation Example

```html
<style>
  [theme="dark"] [is="snapshot-root"] {
    background-color: #1c1c1e; /* Placeholder background in dark mode */
  }
</style>
```

### Custom Navigation Bar Offset Example

```html
<style>
  [is="snapshot-root"] div {
    transform: translateY(calc(var(--app-device-navbar-height, 44px) + var(--app-device-status-height, 20px)));
  }
</style>
```

## Parameter Explanation

| Parameter | Values | Description | Version / Dependency |
| ---- | ------ | ---- | -------- |
| `data-version` | `v2` | Skeleton style version tag (fixed) | - |
| `data-remove-type` | `default` / `manual` | Removal mode: `default` auto removes after page render; `manual` requires calling `removeSnapshot({ animation?: boolean })` to control timing | `manual` requires base library >= 2.29.0 |

When using `manual` mode, you can manually remove in page lifecycle:

```javascript
usePageEvent('onLoad', () => {
  const pages = getCurrentPages();
  const currentPage = pages[pages.length - 1];
  // Ensure base library >= 2.29.0 and template sets data-remove-type="manual"
  currentPage.removeSnapshot({ animation: false }); // animation: true enables fade-out transition
});
```

## FAQ & Troubleshooting

| Phenomenon | Possible Cause | Handling |
| ---- | -------- | -------- |
| An element not generated | Element has no height or parent layout lost due to positioning | Check if `position: fixed` inside causes parent height loss; ensure correct capture range |
| Skeleton misaligned with real content | Custom navigation bar height not offset | Add navigation offset styles or confirm nav config |