Docs

1. Cài đặt

$ npm install next-live2d

2. Import và dùng cơ bản

Component là client component, cần chạy phía client (App Router: đặt trong file có 'use client' hoặc gọi trực tiếp trong layout/page đã là client).

'use client'
import { Live2DWidget } from 'next-live2d'

export default function Page() {
  return <Live2DWidget modelName="Kar98k-normal" />
}

3. Chỉnh kích thước / vị trí

Widget render trong 1 iframe cách ly, dùng width/height để đặt khung gốc, scale để phóng to/thu nhỏ, và bottomOffset để đẩy widget lên/xuống.

<Live2DWidget
  modelName="Kar98k-normal"
  width={200}
  height={400}
  scale={0.9}
  bottomOffset={-20}
  position="right"
/>

4. Chọn model

Truyền tên model dựng sẵn vào modelName, hoặc dùng random để chọn ngẫu nhiên:

<Live2DWidget random />

Danh sách model dựng sẵn (38):

histoirebilibili-22bilibili-33cat-blackcat-whitechinodateganyuhalloharutohibikiHK416-1-normalHK416-2-destroyHK416-2-normalKar98k-normalkobayaxikoharukp31live_uumaimurakumoPioplateletplatelet_2potion-Maker-Pioremrem_2senkoshizukushizuku_48shizuku_pajamaterisatiaumaruuniwed_16xisitinaz16

5. Props

Prop	Kiểu	Mặc định	Mô tả
modelName	string	'histoire'	Tên model dựng sẵn (xem danh sách bên dưới) hoặc tên thư mục model tự host.
baseUrl	string	GitHub raw của next-live2d	Đường dẫn gốc để tải model.json, dùng khi tự host model riêng.
width / height	number	180 / 300	Kích thước khung hiển thị widget (px), trước khi áp dụng scale.
scale	number	1	Tỉ lệ phóng to/thu nhỏ widget quanh góc neo (bottom-left/right).
bottomOffset	number	0	Khoảng lệch so với đáy màn hình (px), có thể âm để đẩy widget xuống thấp hơn.
position	'left' \| 'right'	'right'	Vị trí neo widget theo cạnh màn hình.
opacity / hoverOpacity	number	0.8 / 0.2	Độ trong suốt mặc định và khi hover chuột qua widget.
showOnMobile	boolean	true	Có hiển thị widget trên thiết bị di động hay không.
random	boolean	false	Chọn ngẫu nhiên 1 model trong danh sách dựng sẵn, giữ nguyên cho tới khi component unmount.
onLoad / onError / onClick	function	—	Callback khi widget load xong, gặp lỗi, hoặc được click.
fallback	ReactNode	—	UI hiển thị trong lúc widget đang load.
className / style	string / CSSProperties	—	Áp dụng cho iframe bọc ngoài widget.

6. Custom model host

Muốn tự host model riêng (không dùng model dựng sẵn), trỏ baseUrl tới thư mục chứa các model, mỗi model nằm trong 1 thư mục con có model.json:

<Live2DWidget
  baseUrl="https://example.com/models"
  modelName="my-custom-model"
/>