l2d-widget

l2d-widget is a lightweight Live2D web widget library built on top of l2d. It allows you to add a Live2D model to any webpage with a single line of code. The library is implemented using pure native DOM and has no dependencies on UI frameworks.

Key interactive features include:

• Floating Menu: A menu that appears on hover, supporting custom buttons.
• Tooltip Bubbles: Supports welcome messages, looping messages, typing animations, and lip-syncing.
• Multi-Model Switching: Allows users to switch between models provided in an array.
• Status Bar: Displays loading progress and sleep/wake states.
• Entrance Animations: Supports slide-in or fade-in transition effects.

You can install l2d-widget using any of the standard JavaScript package managers.

npm install l2d-widget

pnpm add l2d-widget

yarn add l2d-widget

By enabling the typing property in the tips configuration, text will appear character-by-character rather than all at once. You can control the speed of this animation.

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

Control how the widget animates when appearing or disappearing using transitionType and transitionDuration.

• transitionType: Set to 'slide' (default) or 'fade'.
• transitionDuration: The animation duration in milliseconds. The default is 1500ms.

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

You can control where the widget appears on the screen using the position option in createWidget. The available options are:

• 'bottom-left' (default)
• 'bottom-right'

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

Tip bubbles appear above the model and can be used to display welcome messages or looping messages. Configuration is defined per model within the createWidget call.

Key properties:

• welcomeMessage: An array of strings to show when the model first loads.
• messages: An array of strings for looping messages.
• duration: How long each message is displayed (in milliseconds). Default is 3000.
• interval: The time between switching messages (in milliseconds). Default is 5000.

createWidget({
  model: {
    path: '/models/model.json',
    tips: {
      welcomeMessage: ['欢迎来访！', '好久不见！'],
      messages: ['记得多休息哦～', '有什么可以帮你的吗？'],
      duration: 3000, // Display each message for 3 seconds
      interval: 5000, // Switch messages every 5 seconds
    },
  },
});

The menu is a set of circular buttons that appear when hovering over the model. You can customize the menu by adding extra items, replacing the entire menu, or changing its alignment via the menus configuration object in createWidget.

createWidget({
  model: { path: '/models/model.json' },
  menus: {
    // Configuration options go here
  }
});

You can install l2d-widget using any major package manager. This is the recommended method for modern web development workflows.

npm install l2d-widget

pnpm add l2d-widget

yarn add l2d-widget

Use the primaryColor option to tint UI elements such as the menu, status bar, and tip bubbles. This accepts standard CSS color values (e.g., hex, RGB, RGBA).

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

To enable multi-model switching, pass an array of model objects to the model property in the createWidget configuration instead of a single object. When an array is provided, a "Switch Model" button is automatically added to the widget menu without additional configuration.

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

Use the createWidget() function to integrate a Live2D model into your webpage. This single call handles canvas creation, WebGL initialization, model loading, and interaction binding. By default, a character will appear in the bottom-left corner of the page with a floating menu and tooltips.

import { createWidget } from 'l2d-widget';

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