# lucky-canvas: A Cross-Platform Lottery Animation Library for Web and Mini Programs

> lucky-canvas is a TypeScript library that renders three lottery animation types, spinning wheel, 9-grid grid picker, and slot machine, from a single codebase that targets vanilla JavaScript, Vue, React, Taro, UniApp, and WeChat mini programs. It handles DPR scaling automatically and supports both synchronous and asynchronous prize drawing modes.

**buuing/lucky-canvas** — 🎖🎖🎖 基于 TS + Canvas 开发的【大转盘 / 九宫格 / 老虎机】抽奖插件，🌈 一套源码适配多端框架 JS / Vue / React / Taro / UniApp / 微信小程序等，🎨 奖品 / 文字 / 图片 / 颜色 / 按钮均可配置，支持同步 / 异步抽奖，🎯 概率前 / 后端可控，🚀 自动根据 dpr 调整清晰度适配移动端

- Repository: https://github.com/buuing/lucky-canvas
- Website: https://100px.net
- Stars: 8,772 · Forks: 1,031
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/buuing-lucky-canvas

## What lucky-canvas Provides

Lottery-style animations are a common UI pattern in promotional and gamification contexts: a spinning wheel that lands on a prize, a 9-cell grid that highlights a winner, or a slot machine that scrolls and stops. Building one from scratch against a Canvas API requires handling animation timing, prize probability distribution, DPR scaling for mobile screens, and the differences between browser canvas and WeChat mini program canvas.

lucky-canvas solves this by providing a configurable component for all three animation types, packaged separately for each major frontend environment. The library is written in TypeScript and targets JS/jQuery, Vue, React, Taro 3.x, UniApp, and WeChat mini programs. The npm package names for these are `lucky-canvas`, `@lucky-canvas/vue`, `@lucky-canvas/react`, `@lucky-canvas/uni`, `@lucky-canvas/taro`, and `@lucky-canvas/mini` respectively.

The library automatically adjusts canvas resolution based on the device pixel ratio, which prevents blurry rendering on high-DPI mobile screens. This is handled internally without additional configuration from the developer.

## Three Animation Types and Configuration

The spinning wheel (大转盘) rotates a wheel and stops at a selected prize segment. The 9-grid (九宫格) lights up cells in sequence around a 3x3 grid and stops on the winner. The slot machine (老虎机) scrolls columns of symbols and stops each column in sequence.

All three types share the same configuration model. Prizes (奖品), labels, images, background colors, and button appearance are all configurable through properties passed to the component. The official documentation covering the full property API is at 100px.net and is currently available only in Chinese. The README notes that the project author is seeking contributors to translate the documentation into English.

Prize probability can be controlled either on the frontend or by the backend. The library supports two drawing modes: synchronous, where the probability calculation happens in the client before the animation starts, and asynchronous, where the client starts the animation and waits for a server response to determine the winner before stopping. The asynchronous mode is designed for cases where server-side verification of the prize is required.

## Monorepo Layout and Development Setup

The repository is organized as a lerna monorepo. The `packages/` directory contains the individual framework adapters. The root `package.json` uses workspaces and defines scripts for building all packages or developing a specific adapter.

The root install uses lerna:

```bash
lerna bootstrap
```

To run the development build for the Vue adapter alongside the core package:

```bash
lerna run --scope=lucky-canvas --scope=@lucky-canvas/vue dev --parallel
```

To build all packages in dependency order:

```bash
lerna run build --sort --stream
```

End users of the library do not interact with the monorepo directly. They install the appropriate npm package for their framework from the public npm registry and import the component. The website at 100px.net serves as the documentation and demo entry point.

## Cross-Platform Trade-Offs

The cross-platform approach means the library handles the differences between browser Canvas and WeChat mini program canvas internally. A developer using `@lucky-canvas/mini` for a WeChat mini program gets the same configuration API as one using `@lucky-canvas/vue` for a web app.

The trade-off is that the library owns the rendering logic entirely. Custom animation curves, irregular prize segment shapes, or non-standard grid layouts that fall outside the three supported types are not achievable with lucky-canvas. Developers with unusual animation requirements would need to implement directly against the Canvas API or use a general-purpose animation library.

A widely known alternative for custom interactive canvas work is Konva.js, which provides a scene graph over the Canvas 2D API for building arbitrary interactive diagrams and animations. Konva gives more control but requires the developer to implement the lottery logic, animation timing, and mobile scaling themselves. lucky-canvas makes those choices for the developer, which is the correct tradeoff when the three supported animation types fit the requirement.

## Documentation Gap and Maintenance

The most significant practical limitation is documentation language. The README is in Chinese, the official documentation at 100px.net is in Chinese, and the component API is documented only in Chinese. The README explicitly acknowledges this, with the author asking anyone who can translate the documentation to contact them.

For a developer not reading Chinese, using the library means either using a machine translation of the documentation or finding community-contributed guides in English. The npm package itself includes TypeScript type definitions, which provide some self-documentation through editor intellisense without consulting the web docs.

The repository had its last push on 2026-07-30, and the library is licensed under Apache 2.0. The Apache 2.0 licence permits commercial use, modification, distribution, and patent use, with requirements to include the licence notice and a NOTICE file in distributions. The project has no GitHub releases, so version tracking requires monitoring the individual npm packages for each framework adapter.

## Conclusion

lucky-canvas is worth considering for any web or mini-program project that needs a lottery or randomized-reward interaction and targets multiple frontend frameworks from a single implementation. Its coverage of WeChat mini programs alongside mainstream web frameworks is uncommon in the field. The main constraint is that the official documentation at 100px.net is in Chinese only. The repository had its last push on 2026-07-30, and the project is licensed under Apache 2.0.

## FAQ

### What frameworks does lucky-canvas support?

lucky-canvas provides separate npm packages for vanilla JS and jQuery (lucky-canvas), Vue (@lucky-canvas/vue), React (@lucky-canvas/react), UniApp (@lucky-canvas/uni), Taro 3.x (@lucky-canvas/taro), and WeChat mini programs (@lucky-canvas/mini). All packages share the same configuration model.

### Does lucky-canvas support server-controlled prize probability?

Yes. The library supports both synchronous and asynchronous drawing modes. In asynchronous mode the animation starts on the client, then waits for a server response before stopping, allowing backend-controlled prize determination.

### Where is the lucky-canvas documentation?

The official documentation and interactive demos are at 100px.net. Currently the documentation is in Chinese only. The README notes the author is looking for contributors to help translate it into English.

## Sources

- [buuing/lucky-canvas on GitHub](https://github.com/buuing/lucky-canvas)
- [Issues](https://github.com/buuing/lucky-canvas/issues)
- [License: Apache-2.0](https://github.com/buuing/lucky-canvas/blob/master/LICENSE)
- [Project website](https://100px.net)
- [README](https://github.com/buuing/lucky-canvas/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/buuing-lucky-canvas