https://github.com/hacxy/l2d-widget
Drop a Live2D character onto any web page. One function call, zero framework dependencies.
https://github.com/hacxy/l2d-widget
cubism2 cubism4 cubism5 live2d live2d-component live2d-web live2d-widget
Last synced: 30 days ago
JSON representation
Drop a Live2D character onto any web page. One function call, zero framework dependencies.
- Host: GitHub
- URL: https://github.com/hacxy/l2d-widget
- Owner: hacxy
- License: mit
- Created: 2022-12-28T18:05:47.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2026-05-25T08:43:50.000Z (about 1 month ago)
- Last Synced: 2026-05-25T10:11:30.662Z (about 1 month ago)
- Topics: cubism2, cubism4, cubism5, live2d, live2d-component, live2d-web, live2d-widget
- Language: TypeScript
- Homepage: https://l2d-widget.hacxy.cn
- Size: 6.5 MB
- Stars: 559
- Watchers: 5
- Forks: 35
- Open Issues: 19
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
l2d-widget
Drop a Live2D character onto any web page. One function call, zero framework dependencies.
[Documentation](https://l2d-widget.hacxy.cn) | [中文](./README.zh.md)
> [!IMPORTANT]
> This project is a full rewrite of [oh-my-live2d](https://github.com/hacxy/oh-my-live2d) based on the [l2d](https://github.com/hacxy/l2d) library. The original `oh-my-live2d` has been renamed to **l2d-widget**. If you are migrating from `oh-my-live2d`, please refer to the [documentation](https://l2d-widget.hacxy.cn) for the updated API.
## Features
- **Single-call integration** — `createWidget()` handles canvas creation, WebGL context initialization, model loading, and interaction bindng in one call
- **Cubism 2 & 6 runtime** — built on [l2d](https://github.com/hacxy/l2d), auto-detects model version and loads the correct Cubism runtime
- **Lip-sync via parameter driving** — character-by-character typing animation drives mouth open/close parameters (`PARAM_MOUTH_OPEN_Y`) in real time with configurable value ranges
- **Full lifecycle control** — `switchModel()` runs exit transition → WebGL teardown → re-init → entrance transition as one atomic async operation; `destroy()` guarantees resource cleanup
- **~500 lines, zero runtime deps** — pure DOM + CSS Animation, no framework. Outputs ESM and IIFE, tree-shakeable
## Installation
```bash
npm install l2d-widget
```
Or use a CDN:
```html
```
## Quick Start
```ts
import { createWidget } from 'l2d-widget';
const widget = createWidget({
model: {
path: 'https://model.hacxy.cn/cat-black/model.json',
},
});
```
A Live2D model appears in the bottom-left corner of the page with a hover menu and tip bubbles. The returned `widget` object gives you programmatic control (switch models, sleep, destroy).
## Examples
### Multi-Model Switching
```ts
createWidget({
model: [
{ path: '/models/cat-black/model.json' },
{ path: '/models/cat-white/model.json' },
],
});
```
A shuffle button appears automatically in the menu when multiple models are provided.
### Typing Animation with Lip-Sync
```ts
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,
},
},
});
```
## Widget Instance
`createWidget()` returns a `Widget` object:
| Method / Property | Description |
| -------------------- | ---------------------------------------- |
| `l2d` | Underlying `l2d` instance |
| `switchModel(index)` | Switch to a model by index |
| `sleep()` | Hide model; click the status bar to wake |
| `destroy()` | Tear down widget and release resources |
For the full options reference (`WidgetOptions`, `ModelOptions`, `MenusOptions`, `TipsOptions`), see the [documentation](https://l2d-widget.hacxy.cn).
## Development
| Command | Purpose |
| ------------ | ----------------------------- |
| `pnpm dev` | Watch build with sourcemaps |
| `pnpm demo` | Demo server at localhost:3000 |
| `pnpm build` | Production build |
| `pnpm lint` | Lint |
## License
[MIT](LICENSE)
---
> 中文文档请见 [README.zh.md](./README.zh.md)