stevenjoezhang/live2d-widget: Adding a Live2D Character to a Web Page

What live2d-widget Is For and Who Should Install It

The project places a Live2D character, commonly called a kanban musume, in the corner of a web page. It is written in TypeScript, and the README states that apart from Live2D Cubism Core there are no other runtime dependencies. The intended audience is a site owner who wants the character without writing WebGL code: a personal blog, a documentation site, a marketing page. The README points at a Hexo blog as a live example, and the repository carries demo pages including demo/demo.html and a login page mockup. The package is published to npm as live2d-widgets, and the repository itself contains no model files. That last point decides a lot. You get the widget, the stylesheet, the tip triggers and the loader; you bring the character assets from somewhere else and point the widget at them.

How the Widget Loads: autoload.js, waifu-tips.js and the initWidget Function

The data flow is short enough to follow. A script tag pulls in dist/autoload.js, which loads two further files, waifu.css and waifu-tips.js. The second of those defines a function called initWidget, which takes one Object argument holding the configuration. That object is where the interesting decisions live. waifuPath points at the JSON file that maps CSS selectors to the text the character says; cdnPath points at a model repository; cubism2Path and cubism5Path point at the two Cubism Core builds; modelId selects the default model; tools lists which small buttons appear; drag enables dragging; showToggleAfterQuit controls whether a close button is permanent; logLevel sets verbosity. The README notes that Cubism Core and related code are loaded dynamically based on the detected model version, which is how the project covers both Cubism 2 and Cubism 3 and newer models without shipping both cores up front. The tip file is the part most people underestimate. Its default selector rules target the Hexo NexT theme, so on any other site they will mostly miss, and the README carries an explicit warning that the contents of waifu-tips.json may not suit all ages or a workplace setting.

Installing live2d-widget and Getting a First Character on the Page

The quickest path is the one the README gives for people who want only the basics: paste a single script tag into the head or body of the page. The README uses version 1.0.1 in that URL, and the package.json in the repository also reports 1.0.1, so the two agree.

<script src="https://fastly.jsdelivr.net/npm/[email protected]/dist/autoload.js"></script>

After that tag loads, the widget fetches its stylesheet, its tip file and a model repository, and the character should appear in a corner of the viewport. If it does not, the README's own debugging advice is to open autoload.js and live2d.min.js directly in the browser and confirm the files arrive complete and correct.

To build from source instead, clone the repository and install dependencies. Node.js and npm are the stated requirements.

https://github.com/stevenjoezhang/live2d-widget.git
npm install

Then compile. The README describes the pipeline precisely: TypeScript in src/ compiles to build/, and build/ is bundled further into dist/.

npm run build

Models are separate. The README says this repository contains none, and that a model repository must be configured through the cdnPath option. Since 1.0 the widget reads the model list on the client, so no backend is required: serving model_list.json plus the model textures statically is enough, and the README notes that a textures.cache file is what enables outfit switching. If you want Cubism 3 or newer models, you must download and unpack Cubism SDK for Web into src/ yourself, for example as src/CubismSdkForWeb-5-r.4, because the Live2D licence terms prevent the project from including that source. For Cubism 2 models only, that step can be skipped.

Where live2d-widget Gets in the Way

The widget owns a piece of the page. It injects DOM, loads a stylesheet, and listens on selectors you define. That is fine on a static blog and awkward inside a single-page application whose router swaps content without a full reload. The README addresses this directly for PJAX: because the character does not need to reload on every navigation, the script has to sit outside the region PJAX replaces. Get that wrong and you get either a duplicate character or a character that vanishes after the first navigation. The tip file is the second sharp edge. Default rules are written for the NexT theme, so on a custom site you are editing JSON by hand to make the character react to anything at all, and the README's warning about content suitability puts that editing on you rather than on the project. Third, self-hosting has a specific failure mode the README calls out: the live2d_path constant must end with a trailing slash. Point it at the directory, not the file, or the loader will not find its assets. Finally, the widget is a presentation layer and nothing more. If you need a character animated inside a canvas that you already control, pulling in a widget that mounts its own DOM is the wrong direction; the README itself points to pixi-live2d-display for that kind of work.

live2d-widget Against pixi-live2d-display and a Hand-Rolled Backend

The README lists pixi-live2d-display as further reading, and the two sit at different levels. live2d-widget is an application: it decides where the character sits, what buttons it has, when it speaks, and how it is dismissed. pixi-live2d-display is a rendering layer built on PixiJS, which means you supply the scene graph, the interaction model and the UI. If your site is a blog, the widget saves you all of that. If your site is a canvas application, the widget's opinions become obstacles and the lower-level library is the better fit. The other comparison is historical and internal to this project. Older versions of initWidget accepted an apiPath parameter and expected you to run a backend, with live2d_api named as the reference implementation, that aggregated model resources and generated JSON descriptions dynamically. Since 1.0 that work moved to the front end, and the README states apiPath is no longer needed because all model resources can be served statically. Anyone following a tutorial written before 1.0 will be configuring a server that the current version does not ask for.

Licence, Maintenance and the Cost of Upgrading

The repository is licensed GPL-3.0-or-later, and package.json states the same. That matters for a widget you embed in a page: the GPL is a copyleft licence, and how it interacts with your site's own code is a question for your own counsel, not something this article can settle. The Live2D side is separate and the README is explicit about it. Cubism SDK for Web cannot be bundled because of the Live2D Proprietary Software License Agreement and the Live2D Open Software License Agreement, so if you need Cubism 3 or newer models you download the SDK yourself and place it under src/. The README also states that the code in the repository satisfies the Redistributable Code clauses of the Live2D licence. On maintenance, the last push to the repository was on 2026-09-19, and the most recent release listed is v0.9.0 from 2022-12-27, while package.json reports 1.0.1; the release list and the package version are not in step, so pin the version you install rather than assuming a tag exists for it. Upgrading has two recurring costs. The tip file is yours to maintain once you leave the NexT defaults. And the CDN path in the README is versioned, so bumping the widget means editing the script URL, or forking the repository and pushing a new git tag, which the README notes is required before @latest on jsDelivr will serve the updated files, with CDN caching adding further delay. Cloudflare Pages is offered as an alternative deployment, with npm run build as the build command.

Editorial conclusion

Adopt live2d-widget if you run a static blog or a hand-written site and want a character layer that is one script tag deep, and you accept that you must supply a model repository and review waifu-tips.json yourself. Do not adopt it if you need an animated character inside a canvas app, a game, or a framework whose router you do not control, because the widget mounts its own DOM and the README warns about PJAX. Verify first that your model repository serves model_list.json and that the path you pass as cdnPath resolves, then confirm your build step copies dist/ intact.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. stevenjoezhang/live2d-widget on GitHub