### Install with npm

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/en/guide/installation.md

Use npm to install the l2d-widget package.

```bash
npm install l2d-widget
```

--------------------------------

### Setup with CDN

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/en/guide/installation.md

Include the widget using a CDN script tag and initialize it with L2D_WIDGET.createWidget.

```html
<script src="https://unpkg.com/l2d-widget/dist/index.min.js"></script>
<script>
  L2D_WIDGET.createWidget({
    model: {
      path: 'https://model.hacxy.cn/cat-black/model.json',
    },
  })
</script>
```

--------------------------------

### Minimal Live2D Widget Setup

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/en/guide/quick-start.md

This snippet shows the basic setup to create a Live2D widget with default settings. It imports the necessary function and specifies the model path.

```typescript
import { createWidget } from 'l2d-widget';

const widget = createWidget({
  model: {
    path: 'https://model.hacxy.cn/cat-black/model.json',
  },
});
```

--------------------------------

### Install with pnpm

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/en/guide/installation.md

Use pnpm to add the l2d-widget package to your project.

```bash
pnpm add l2d-widget
```

--------------------------------

### Install with yarn

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/en/guide/installation.md

Use yarn to add the l2d-widget package to your project.

```bash
yarn add l2d-widget
```

--------------------------------

### Customizing Live2D Widget Position and Size

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/en/guide/quick-start.md

This example demonstrates how to customize the widget's position on the screen and its canvas size. It overrides the default position to 'bottom-right' and sets the size to 400 pixels.

```typescript
createWidget({
  model: {
    path: 'https://model.hacxy.cn/cat-black/model.json',
  },
  position: 'bottom-right', // bottom-right corner
  size: 400, // canvas size 400px
});
```

--------------------------------

### Basic Tips Configuration

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/en/guide/tips.md

Configure welcome messages, tips messages, display duration, and switch interval for the speech bubble.

```typescript
createWidget({
  model: {
    path: '/models/model.json',
    tips: {
      welcomeMessage: ['Welcome!', 'Nice to see you!'],
      messages: ['Take a break~', 'Need any help?'],
      duration: 3000, // display for 3s (default)
      interval: 5000, // switch every 5s (default)
    },
  },
});
```

--------------------------------

### Basic Live2D Widget Initialization

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/en/examples/index.md

Demonstrates the minimum configuration required to display a Live2D model. Ensure the model path is correct.

```typescript
import { createWidget } from 'l2d-widget';

createWidget({
  model: {
    path: 'https://model.hacxy.cn/cat-black/model.json',
  },
});
```

--------------------------------

### Initialize Dark Mode Preference

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/demos/runner.html

This snippet checks local storage and system preferences to apply the 'dark' class to the HTML element, enabling dark mode.

```javascript
/* { margin: 0; padding: 0; } html, body { width: 100%; height: 100%; overflow: hidden; background: #f9fafb; } html.dark body { background: #1a1a1a; } */
const stored = localStorage.getItem('vitepress-theme-appearance')
const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches

if (stored === 'dark' || (stored !== 'light' && prefersDark)) {
  document.documentElement.classList.add('dark')
}
```

--------------------------------

### Enable Typing Animation

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/en/guide/tips.md

Enable character-by-character typing animation for tips and set the typing speed.

```typescript
const options = {
  tips: {
    typing: {
      speed: 100, // 100ms per character (default)
    },
  },
};
```

--------------------------------

### Per-Model Configuration

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/en/guide/multi-model.md

Customize individual models by specifying scale, offset, and tips for each entry in the `model` array. This allows for unique settings per model.

```typescript
createWidget({
  model: [
    {
      path: '/models/cat-black/model.json',
      scale: 1.2,
      tips: {
        welcomeMessage: ['I am the black cat!'],
      },
    },
    {
      path: '/models/cat-white/model.json',
      offset: [0.5, 0],
      tips: {
        welcomeMessage: ['I am the white cat!'],
      },
    },
  ],
});
```

--------------------------------

### Configure Multiple Models

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/en/guide/multi-model.md

Pass an array of model paths to the `model` option to enable multi-model switching. A 'Switch Model' button will appear automatically in the menu.

```typescript
createWidget({
  model: [
    { path: '/models/cat-black/model.json' },
    { path: '/models/cat-white/model.json' },
  ],
});
```

--------------------------------

### Live2D Widget with Position and Transition

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/en/examples/index.md

Configures the widget's placement on the screen and applies a fade-in transition effect. Useful for controlling the widget's appearance.

```typescript
createWidget({
  model: {
    path: 'https://model.hacxy.cn/cat-black/model.json',
  },
  position: 'bottom-right',
  transitionType: 'fade',
});
```

--------------------------------

### Typing Animation with Lip-Sync

Source: https://github.com/hacxy/l2d-widget/blob/main/README.md

Enable typing animation and lip-sync for the Live2D character. Configure the `PARAM_MOUTH_OPEN_Y` parameter and other message-related options within the `tips` object.

```typescript
createWidget({
  model: {
    path: '/models/cat-black/model.json',
    tips: {
      typing: {
        param: 'PARAM_MOUTH_OPEN_Y',
        speed: 200,
      },
      welcomeMessage: ['Hello!', 'Nice to meet you!'],
      messages: ['Take a break~', 'Stay hydrated!'],
      duration: 4000,
      interval: 6000,
    },
  },
});
```

--------------------------------

### Basic HTML Structure for Hero Component

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/demos/hero.html

This snippet shows the fundamental HTML elements that constitute the Hero component, including a container for the editor and its body.

```html
<div class="editor">
  <div class="editor-body"></div>
  <div class="editor-toolbar"></div>
</div>
```

--------------------------------

### Live2D Widget with Typing Animation and Lip-Sync

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/en/examples/index.md

Configures typing animation with lip-sync functionality, using a specified mouth parameter. This enhances the character's interactivity.

```typescript
createWidget({
  model: {
    path: 'https://model.hacxy.cn/cat-black/model.json',
    tips: {
      offset: { y: -28, x: 10 },
      typing: {
        param: 'PARAM_MOUTH_OPEN_Y',
        speed: 200,
        minValue: 0,
        maxValue: 1,
      },
      welcomeMessage: ['Hello, I am a cat!', 'Nice weather today~'],
      messages: ['Stay hydrated!', 'Rest your eyes~', 'Keep going!'],
      duration: 4000,
      interval: 6000,
    },
  },
});
```

--------------------------------

### Lip-Sync with Typing Animation

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/en/guide/tips.md

Enable lip-sync for the model's mouth during typing animation by specifying the mouth parameter and its range.

```typescript
const options = {
  tips: {
    typing: {
      param: 'PARAM_MOUTH_OPEN_Y', // mouth parameter name
      speed: 200,
      minValue: 0, // min mouth open value (0~1)
      maxValue: 1, // max mouth open value (0~1)
    },
  },
};
```

--------------------------------

### Include l2d-widget via CDN

Source: https://github.com/hacxy/l2d-widget/blob/main/README.md

Include the l2d-widget script from a CDN in your HTML file. This allows you to use the widget without a package manager.

```html
<script src="https://unpkg.com/l2d-widget/dist/index.min.js"></script>
```

--------------------------------

### CSS for Hero Component Styling

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/demos/hero.html

This CSS provides styling for the Hero component, including layout, typography, colors, and transitions for elements like the editor, body, and toolbar. It also includes styles for keywords, functions, strings, properties, and punctuation.

```css
* { margin: 0; padding: 0; box-sizing: border-box; }
html, body { width: 100%; height: 100%; overflow: hidden; font-family: system-ui, sans-serif; }
html { background: #ffffff; }
html.dark { background: #1b1b1f; }
.editor { position: absolute; inset: 0; display: flex; flex-direction: column; transition: opacity 0.5s ease; }
.editor.hidden { opacity: 0; pointer-events: none; }
.editor-body { flex: 1; padding: 16px 20px; overflow: hidden; white-space: pre-wrap; word-break: break-all; font-family: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, monospace; font-size: 12px; line-height: 1.7; color: #383a42; background: #fafafa; }
html.dark .editor-body { color: #abb2bf; background: #1e1e1e; }
.editor-toolbar { display: flex; justify-content: flex-end; align-items: center; padding: 8px 12px; background: #f0f0f0; border-top: 1px solid rgba(0, 0, 0, 0.06); }
html.dark .editor-toolbar { background: #252526; border-top-color: rgba(255, 255, 255, 0.06); }
.run-btn { padding: 5px 18px; border: none; border-radius: 4px; font-size: 13px; cursor: pointer; background: rgba(255, 130, 160, 0.9); color: #fff; opacity: 0; transform: scale(0.95); transition: opacity 0.3s, transform 0.3s, filter 0.15s; }
.run-btn.visible { opacity: 1; transform: scale(1); }
.run-btn.pressed { filter: brightness(0.85); transform: scale(0.93); }
.kw { color: #a626a4; }
.fn { color: #4078f2; }
.str { color: #50a14f; }
.prop { color: #e45649; }
.punc { color: #383a42; }
html.dark .kw { color: #c678dd; }
html.dark .fn { color: #61afef; }
html.dark .str { color: #98c379; }
html.dark .prop { color: #e06c75; }
html.dark .punc { color: #abb2bf; }
.cursor { display: inline-block; width: 2px; height: 1.1em; background: #383a42; vertical-align: text-bottom; animation: blink 1s step-end infinite; }
html.dark .cursor { background: #abb2bf; }
@keyframes blink { 50% { opacity: 0; } }
.mouse-ptr { position: absolute; width: 20px; height: 20px; opacity: 0; z-index: 10; pointer-events: none; transition: top 0.6s cubic-bezier(0.33, 1, 0.68, 1), left 0.6s cubic-bezier(0.33, 1, 0.68, 1), opacity 0.3s; }
.mouse-ptr.visible { opacity: 1; }
```

--------------------------------

### JavaScript for Theme Switching and Cursor Effects

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/demos/hero.html

This JavaScript handles theme switching based on URL parameters or messages, and manages the visibility and animation of a mouse pointer element. It also includes a blinking cursor animation.

```javascript
if (new URLSearchParams(location.search).get('dark') === '1') document.documentElement.classList.add('dark')
window.addEventListener('message', function (e) {
  if (e.data && e.data.type === 'theme-change') {
    document.documentElement.classList.toggle('dark', e.data.dark)
  }
})
```

--------------------------------

### Programmatic Model Switching

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/en/guide/multi-model.md

Switch between configured models using the `widget.switchModel(index)` method. This method handles the exit and entrance animations for a smooth transition.

```typescript
const widget = createWidget({
  model: [
    { path: '/models/cat-black/model.json' },
    { path: '/models/cat-white/model.json' },
  ],
});

// Switch to the second model
await widget.switchModel(1);
```

--------------------------------

### Set Widget Transition Type and Duration

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/en/guide/position.md

Configure the widget to use a 'fade' transition for entrance and exit animations, with a duration of 1000ms. The default duration is 1500ms.

```typescript
createWidget({
  model: { path: '/models/model.json' },
  transitionType: 'fade',
  transitionDuration: 1000, // animation duration 1000ms (default 1500)
});
```

--------------------------------

### Live2D Widget with Multiple Models

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/en/examples/index.md

Enables switching between multiple Live2D models. The widget automatically displays a switch button when more than one model is configured.

```typescript
createWidget({
  transitionType: 'fade',
  position: 'bottom-right',
  model: [
    { path: 'https://model.hacxy.cn/cat-black/model.json' },
    { path: 'https://model.hacxy.cn/cat-white/model.json' },
  ],
});
```

--------------------------------

### Set Widget Position

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/en/guide/position.md

Configure the widget to appear on the bottom-right of the screen. The default position is 'bottom-left'.

```typescript
createWidget({
  model: { path: '/models/model.json' },
  position: 'bottom-right',
});
```

--------------------------------

### Live2D Widget with Custom Menu Items

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/en/examples/index.md

Adds custom buttons to the widget's menu. This allows for extending the widget's functionality with custom actions.

```typescript
createWidget({
  model: {
    path: 'https://model.hacxy.cn/cat-black/model.json',
  },
  menus: {
    extraItems: [
      {
        icon: 'mdi:emoticon-happy-outline',
        label: 'Play motion',
        onClick(widget) {
          const motions = widget.l2d.getMotions();
          const groups = Object.keys(motions);
          if (groups.length > 0) {
            widget.l2d.playMotion(groups[0]!);
          }
        },
      },
    ],
  },
});
```

--------------------------------

### Set Widget Size (Width and Height)

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/en/guide/position.md

Define separate width and height values for the widget canvas. This allows for non-square dimensions.

```typescript
// Separate width and height
createWidget({
  model: { path: '/models/model.json' },
  size: { width: 350, height: 500 },
});
```

--------------------------------

### Replace Entire Menu

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/en/guide/menu.md

Completely replace the default menu with a custom set of items using `menus.items`. When `menus.items` is set, `menus.extraItems` is ignored.

```typescript
createWidget({
  model: { path: '/models/model.json' },
  menus: {
    items: [
      {
        icon: 'mdi:bed',
        label: 'Sleep',
        onClick(widget) {
          widget.sleep();
        },
      },
    ],
  },
});
```

--------------------------------

### Add Custom Menu Items

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/guide/menu.md

Append custom buttons to the end of the default menu using `menus.extraItems`. Each item requires an icon, label, and an onClick handler.

```typescript
createWidget({
  model: { path: '/models/model.json' },
  menus: {
    extraItems: [
      {
        icon: 'mdi:emoticon-happy-outline',
        label: '播放动作',
        onClick(widget) {
          const motions = widget.l2d.getMotions();
          const groups = Object.keys(motions);
          if (groups.length > 0) {
            widget.l2d.playMotion(groups[0]!); 
          }
        },
      },
    ],
  },
});
```

--------------------------------

### Set Widget Theme Color

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/en/guide/position.md

Apply a custom pink theme color to UI elements like the menu and status bar. The primaryColor tints various interface components.

```typescript
createWidget({
  model: { path: '/models/model.json' },
  primaryColor: 'rgba(255, 130, 130, 0.9)', // pink theme
});
```

--------------------------------

### Replace Default Menu Items

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/guide/menu.md

Completely replace the default menu with a custom set of buttons using `menus.items`. If `items` is set, `extraItems` will be ignored.

```typescript
createWidget({
  model: { path: '/models/model.json' },
  menus: {
    items: [
      {
        icon: 'mdi:bed',
        label: '休眠',
        onClick(widget) {
          widget.sleep();
        },
      },
    ],
  },
});
```

--------------------------------

### Set Widget Size (Square)

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/en/guide/position.md

Set the widget to a square size of 400 pixels. The default canvas size is 300px.

```typescript
// Square 400x400
createWidget({
  model: { path: '/models/model.json' },
  size: 400,
});
```

--------------------------------

### Append Custom Menu Items

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/en/guide/menu.md

Add new buttons to the default menu using `menus.extraItems`. This is useful for adding custom actions without replacing existing ones.

```typescript
createWidget({
  model: { path: '/models/model.json' },
  menus: {
    extraItems: [
      {
        icon: 'mdi:emoticon-happy-outline',
        label: 'Play motion',
        onClick(widget) {
          const motions = widget.l2d.getMotions();
          const groups = Object.keys(motions);
          if (groups.length > 0) {
            widget.l2d.playMotion(groups[0]!); 
          }
        },
      },
    ],
  },
});
```

--------------------------------

### Align Menu to Left

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/en/guide/menu.md

Control the alignment of the menu on the canvas using `menus.align`. The default alignment is 'right'.

```typescript
createWidget({
  model: { path: '/models/model.json' },
  menus: { align: 'left' },
});
```

--------------------------------

### Position Offset for Speech Bubble

Source: https://github.com/hacxy/l2d-widget/blob/main/docs/en/guide/tips.md

Adjust the position of the speech bubble using x and y offsets.

```typescript
const options = {
  tips: {
    offset: { x: 20, y: -10 }, // right 20px, up 10px
  },
};
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.