Background Wallpaper

The background wallpaper configuration controls the site's background image display mode and related effects.

Config File

src/config/backgroundWallpaper.ts

Wallpaper Mode

Property	Type	Default	Description
`mode`	`string`	`"banner"`	Mode: `"banner"` banner, `"fullscreen"` full-screen, `"overlay"` overlay transparent, `"none"` solid color

TIP

The wallpaper mode switch toggle has been moved to displaySettingsConfig.wallpaperModeSwitchable. See Display Settings Panel.

Image Configuration

The src property supports multiple formats:

Separate Desktop and Mobile

src: {
  desktop: "assets/images/DesktopWallpaper/d1.avif",
  mobile: "assets/images/MobileWallpaper/m1.avif",
},

Multiple Images (Random)

src: {
  desktop: [
    "assets/images/DesktopWallpaper/d1.avif",
    "assets/images/DesktopWallpaper/d2.avif",
  ],
  mobile: [
    "assets/images/MobileWallpaper/m1.avif",
    "assets/images/MobileWallpaper/m2.avif",
  ],
},

Random Image API

src: {
  desktop: "https://t.alcy.cc/pc",
  mobile: "https://t.alcy.cc/mp",
},

TIP

Image path formats:

public directory (starts with /): not optimized
src directory (no leading /): auto-optimized (recommended)
Remote URL: not optimized, ensure small file size

Avoid renaming your custom images to d1-d6 or m1-m6, as these default sample image names may be overwritten during updates.

Background Video Player

Property	Type	Default	Description
`playerEnable`	`boolean`	`false`	Enable background video player. When enabled, a play button will appear in the navbar
`src.playerUrl`	`string \| string[]`	-	Video URL(s). Supports a single path or an array for multi-video cycling
`common.playerMode`	`"order" \| "random"`	`"order"`	Multi-video playback mode: `"order"` sequential loop, `"random"` random shuffle

export const backgroundWallpaper = {
  playerEnable: true,
  src: {
    desktop: [...],
    mobile: [...],
    // Single video
    // playerUrl: "/assets/videos/firefly.mp4",
    // Multiple videos
    playerUrl: [
      "/assets/videos/video1.mp4",
      "/assets/videos/video2.mp4",
    ],
  },
  common: {
    playerMode: "random",
  },
};

TIP

Place local videos in the public/assets/videos/ directory
The play button is automatically hidden in solid color mode (mode: "none")
In multi-video mode, if a video fails to load, the player automatically tries the next one. A failure toast is shown when all videos fail

Settings under common are shared between banner wallpaper and fullscreen wallpaper modes.

Text Overlay Dim

Property	Type	Default	Description
`common.dimOpacity`	`number`	`0.2`	Banner text overlay darkness, 0-1, higher values = darker

Home Banner Text

Property	Type	Default	Description
`common.homeText.enable`	`boolean`	`true`	Enable banner text
`common.homeText.title`	`string`	`"Lovely firefly!"`	Main title
`common.homeText.titleSize`	`string`	`"3.8rem"`	Title font size
`common.homeText.subtitle`	`string \| string[]`	-	Subtitle(s)
`common.homeText.subtitleSize`	`string`	`"1.5rem"`	Subtitle font size

Typewriter Effect

Property	Type	Default	Description
`common.homeText.typewriter.enable`	`boolean`	`true`	Enable typewriter effect
`common.homeText.typewriter.speed`	`number`	`100`	Typing speed (ms)
`common.homeText.typewriter.deleteSpeed`	`number`	`50`	Delete speed (ms)
`common.homeText.typewriter.pauseTime`	`number`	`2000`	Pause time after completion (ms)

INFO

Typewriter enabled — cycles through all subtitles
Typewriter disabled — randomly shows one subtitle on each refresh

Link Icons Below the Title

Shows a customizable row of link icons (translucent round buttons) below the home banner title.

Property	Type	Default	Description
`common.homeText.linksEnable`	`boolean`	`true`	Show the link icons below the title
`common.homeText.links`	`{ name; url; icon; showName? }[]`	-	List of link icons. Empty to hide

name: link name (used for aria-label / title / optional showName display)
url: link URL (http(s):// external links open in a new tab)
icon: Iconify icon, e.g. fa7-brands:github, fa7-solid:envelope, fa7-solid:rss, mdi:rss
showName: optional, true to show the name next to the icon

homeText: {
  // ...
  links: [
    { name: "GitHub", icon: "fa7-brands:github", url: "https://github.com/CuteLeaf" },
    { name: "Email", icon: "fa7-solid:envelope", url: "mailto:xiaye@msn.com" },
    { name: "RSS", icon: "fa7-solid:rss", url: "/rss/" },
    // optionally show text
    { name: "Blog", icon: "mdi:rss", url: "/rss/", showName: true },
  ],
},

Wallpaper Carousel

Shared carousel configuration for both banner and fullscreen modes. Only works when multiple images are configured.

Property	Type	Default	Description
`common.carousel.enable`	`boolean`	`false`	Enable wallpaper carousel. If disabled, one image is randomly chosen on page refresh
`common.carousel.interval`	`number`	`5000`	Carousel interval in milliseconds
`common.carousel.transitionEffect`	`string`	`"fade"`	Transition effect: `"fade"`, `"zoom"`, `"slide"`, `"kenburns"`

common: {
  carousel: {
    enable: true,
    interval: 5000,
    transitionEffect: "kenburns", // "fade" | "zoom" | "slide" | "kenburns"
  },
},

TIP

The wallpaper carousel user toggle has been moved to displaySettingsConfig.bannerCarouselSwitchable. See Display Settings Panel.

Transition effects:

Effect	Description
`fade`	Cross-fade between images
`zoom`	New image scales up from small to full size
`slide`	New image slides in from the right
`kenburns`	Ken Burns (recommended) — image slowly zooms in while transitioning via LQIP blurred preview bridge for the smoothest effect

Image Position

Property	Type	Default	Description
`banner.position`	`string`	`"0% 20%"`	CSS `object-position` value. Supports `'center'`, `'top'`, `'bottom'`, `'left'`, `'right'`, percentages, etc.

Post Banner Information

Property	Type	Default	Description
`banner.postInfo.mode`	`"description" \| "meta"`	`"description"`	Post banner information mode: `"description"` shows the post description, while `"meta"` shows published/updated dates, word count, and reading time

Property	Type	Default	Description
`banner.navbar.transparentMode`	`string`	`"semi"`	Mode: `"semi"` semi-transparent, `"full"` fully transparent, `"semifull"` dynamic
`banner.navbar.blur`	`number`	`5`	Blur intensity; `0` disables the navbar's frosted glass

INFO

The navbar's dropdown menus and float panels (search, display settings, light/dark, music, mobile menu) always keep a frosted glass. Its blur follows banner.navbar.blur with a minimum of 2px.

So setting blur to 0 only disables the frosted glass on the navbar itself — the panels are unaffected. In pure-color mode (mode: "none") the panels stay opaque.

The fullscreen wallpaper mode's navbar is not affected by this config (it is controlled separately by fullscreen.navbar.dynamicTransparent, see below).

Wave Animation

Property	Type	Default	Description
`banner.waves.enable`	`boolean \| { desktop, mobile }`	`{ desktop: true, mobile: true }`	Enable wave animation

WARNING

Wave animation affects page performance. Enable based on your needs.

TIP

The wave animation user toggle has been moved to displaySettingsConfig.wavesSwitchable. See Display Settings Panel.

Gradient Transition

Automatically enabled when waves are disabled, providing a smooth gradient fade from the wallpaper bottom to the background color.

Property	Type	Default	Description
`banner.gradient.enable`	`boolean \| { desktop, mobile }`	`{ desktop: true, mobile: true }`	Enable gradient transition
`banner.gradient.height`	`string`	`"15vh"`	Gradient height

INFO

Gradient and waves are mutually exclusive: when waves are enabled, the gradient is automatically hidden; when waves are disabled, the gradient is automatically shown. Both user toggles have been moved to displaySettingsConfig. See Display Settings Panel.

Fullscreen Mode

Fullscreen wallpaper mode fixes the background image across the entire screen:

Home page: the first screen shows only the wallpaper with the centered home title; the content area sits below the fold. Scrolling slides the content up over the wallpaper, the title fades out smoothly as it scrolls up, and the wallpaper transitions from crisp to blurred
Other pages: behaves like overlay mode — the wallpaper stays fixed and blurred, content at the top
The wallpaper is opaque (overlay.opacity does not apply); blur (blur), card opacity (cardOpacity) and z-index (zIndex) are reused from the overlay config below
Waves and gradient transitions are not shown

Property	Type	Default	Description
`fullscreen.position`	`string`	`"center"`	CSS `object-position` value
`fullscreen.navbar.dynamicTransparent`	`boolean`	`true`	Enable dynamic transparent navbar: the navbar is transparent at the top of the home page and becomes opaque after scrolling (home page only)
`fullscreen.blurRamp.enable`	`boolean \| object`	`{ desktop: true, mobile: true }`	Blur ramp toggle for the home page scroll (blur ramps from 0 to `overlay.blur` as you scroll). Supports a boolean or per-device `{ desktop, mobile }`; when disabled on a device, fullscreen wallpaper stays crisp there (home and other pages) and the settings-panel blur slider is hidden

fullscreen: {
  position: "center",
  navbar: {
    dynamicTransparent: true,
  },
  blurRamp: {
    enable: {
      desktop: true,
      mobile: true,
    },
  },
},

INFO

In fullscreen mode the navbar is fully transparent by default (transparency is controlled by overlay.cardOpacity). With fullscreen.navbar.dynamicTransparent enabled, the home page's top navbar becomes transparent and shows a card background after scrolling.

TIP

The crisp-to-blurred wallpaper transition on scroll is expensive on mobile GPUs (it re-rasterizes a full-screen blur). If scrolling feels laggy on mobile, set blurRamp.enable.mobile to false — fullscreen wallpaper stays crisp on that device and the settings-panel blur slider is hidden as well.

Overlay Mode

Property	Type	Default	Description
`overlay.zIndex`	`number`	`-1`	Z-index, ensures wallpaper stays in background layer
`overlay.opacity`	`number`	`0.8`	Wallpaper opacity (0-1)
`overlay.blur`	`number`	`10`	Background blur (px)
`overlay.cardOpacity`	`number`	`0.5`	Card background opacity (0-1). Lower values make cards more transparent

TIP

The overlay parameter adjustment toggle has been moved to displaySettingsConfig.overlaySwitchable, supporting master toggle or per-item toggles. See Display Settings Panel.

Background Wallpaper

Config File

Wallpaper Mode

Image Configuration

Separate Desktop and Mobile

Multiple Images (Random)

Random Image API

Background Video Player

Common Configuration (Shared by Banner and Fullscreen)

Text Overlay Dim

Home Banner Text

Typewriter Effect

Link Icons Below the Title

Wallpaper Carousel

Banner Mode

Image Position

Post Banner Information

Navbar Transparency

Wave Animation

Gradient Transition

Fullscreen Mode

Overlay Mode

Background Wallpaper ​

Config File ​

Wallpaper Mode ​

Image Configuration ​

Separate Desktop and Mobile ​

Multiple Images (Random) ​

Random Image API ​

Background Video Player ​

Common Configuration (Shared by Banner and Fullscreen) ​

Text Overlay Dim ​

Home Banner Text ​

Typewriter Effect ​

Link Icons Below the Title ​

Wallpaper Carousel ​

Banner Mode ​

Image Position ​

Post Banner Information ​

Navbar Transparency ​

Wave Animation ​

Gradient Transition ​

Fullscreen Mode ​

Overlay Mode ​

Background Wallpaper

Config File

Wallpaper Mode

Image Configuration

Separate Desktop and Mobile

Multiple Images (Random)

Random Image API

Background Video Player

Common Configuration (Shared by Banner and Fullscreen)

Text Overlay Dim

Home Banner Text

Typewriter Effect

Link Icons Below the Title

Wallpaper Carousel

Banner Mode

Image Position

Post Banner Information

Navbar Transparency

Wave Animation

Gradient Transition

Fullscreen Mode

Overlay Mode