# number-flip > Change number with flipping animation Latest version **1.3.0** (published 2026-07-06) · MIT license · 0 weekly downloads ## Install ```sh npm install number-flip pnpm add number-flip yarn add number-flip bun add number-flip ``` ## Health **Score 60/100 (C)** — status: active. Positive: has types; esm support; no vulnerabilities; recently updated. Warnings: low downloads. ## Facts | | | |---|---| | Version | 1.3.0 | | Published | 2026-07-06 | | First published | 2018-02-02 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Dependencies | 0 | | Unpacked size | 561.4 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 662 | | Author | gaoryrt | | Maintainers | gaoryrt | ## Links - npm: https://www.npmjs.com/package/number-flip - Repository: https://github.com/gaoryrt/flip - Homepage: https://github.com/gaoryrt/flip#readme - Issues: https://github.com/gaoryrt/flip/issues - npm.io page: https://npm.io/package/number-flip ## Recent versions - 1.3.0 (latest) — 2026-07-06 - 1.2.3 — 2024-06-19 - 1.2.2 — 2024-06-19 - 1.2.1 — 2024-06-19 - 1.2.0 — 2024-06-19 - 1.1.10 — 2021-01-07 - 1.1.8 — 2019-10-31 - 1.1.7 — 2019-10-18 - 1.1.6 — 2019-10-18 - 1.1.5 — 2019-10-16 - 1.1.4 — 2019-07-17 - 1.1.2 — 2019-07-17 - 1.1.0 — 2019-07-17 - 1.0.30 — 2019-07-08 - 1.0.28 — 2018-09-30 - … 12 more at https://npm.io/package/number-flip/versions ## README # number-flip [![NPM](https://nodei.co/npm/number-flip.png?mini=true)](https://www.npmjs.com/package/number-flip) Change number with flipping animation ![](./demo.gif) ![](./demo2.gif) [demo on codepen.io](https://codepen.io/gaoryrt/pen/azvNQwX) # install ``` $ npm install --save number-flip ``` # usage ## import `number-flip` ``` import { Flip } from 'number-flip' ``` ## use it! ### create one and make it flip immediately: ```js new Flip({ node: $('.flip'), from: 9527, to: 42 }) ``` ### flip one with delay: ```js new Flip({ node: $('.flip'), from: 9527, to: 42, delay: 1 // second }) ``` ### create one and flip it later: ```js const el = new Flip({ node: $('.flip'), from: 9527 }) el.flipTo({to: 42}) ``` ### customize animation duration: ```js new Flip({ node: document.querySelector('.flip'), from: 9527, to: 42, duration: 2 // second }) ``` ### more complex usage ```js new Flip({ node: document.querySelector('.flip'), from: 73, to: 25, duration: 2, delay: 1, easeFn: function(pos) { if ((pos/=0.5) < 1) return 0.5*Math.pow(pos,3); return 0.5 * (Math.pow((pos-2),3) + 2); }, // for more easing function, see https://github.com/danro/easing-js/blob/master/easing.js systemArr: ['零', '壹', '贰', '叁', '肆', '伍', '陆', '柒', '捌', '玖'] }) ``` ### CSS customizable: HTML structure of a 3-digits flip would be like: ``` .number-flip .ctnr.ctnr0 .digit*10 .ctnr.ctnr1 .digit*10 .ctnr.ctnr2 .digit*10 ``` The height / width of `.number-flip` is based on the height / width of `.digit`, you can customize the size by changing the css of `.digit`: ```css .number-flip { ... } .ctnr { ... } .digit { ... } ``` or you can rename it in config: ```js new Flip({ containerClassName: 'c', digitClassName: 'd', separatorClassName: 's' }) ``` ### separator: Spearator allowed ```js new Flip({ node: $('.flip'), from: 95279527, separator: ',' }) ``` even more ```js new Flip({ node: $('.flip'), from: 95279527, separator: ['万', '亿', '兆'], separateEvery: 4 }) ``` # syntax ```js var flipInstance = new Flip(options) flipInstance.flipTo(instanceOptions) ``` ## return value The returned Flip instance has a function called `flipTo`. `flipTo` takes one `instanceOptions`, so you can start the flip animation whenever you want. ## parameter **`options`** - `node`: An `Element` object representing the animation container. Make sure this element is already existed in the DOM when you `new` the instance. - `from`: The number that animation starts from. `Optional` if you want to flip with 0. Expected a positive integer. - `to`: The number that animation rolls to. `Optional` if you want to start manually. Expected a positive integer. - `duration` `optional`: The animation duration in seconds. If not specified, `duration` defaults to 0.5 second. - `delay` `optional`: The delay of animation in seconds. If not specified, there's no `delay`. - `easeFn` `optional`: A easing function to be executed. If not specified, `easeFn` defaults [easeInOutCubic](https://github.com/danro/easing-js/blob/4f5e7edbde7f7200a1baf08e357377896c0d207e/easing.js#L39-L42). - `systemArr` `optional`: An array ten-lengthed, representing the content of each decimal rolling system. If not specified, `systemArr` defaults to `[ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ]`. - `direct` `optional`: A boolean representing if the number would rolling directly or one by one. For example, from 0 to 99, the ones place would pass 9 digits if is direct. Or if is not directly, would pass 99 digits, 9 rounds for each of the tens place. If not specified, `direct` defaults `true`. - `separator`: A string / array representing the separator, defaults off. Could set to a string or an array-of-string. - `separateOnly`: A number representing the only separator， defaults `0`. - `separateEvery`: The number per digit separator would add to, defaults `3`, won't work if `separateOnly` has been set. **`instanceOptions`** - `to`: Same as `options.to`. - `duration` `optional`: Same as `options.duration`. - `easeFn` `optional`: Same as `options.easeFn`. - `direct` `optional`: Same as `options.direct`. # TODO - [x] flip with FLIP - [x] syntax - [ ] browser compatibility list # license MIT # credit [![](./browserstack-logo-600x315.png)](http://browserstack.com/) Special thanks to [Browserstack](http://browserstack.com/) providing cross-browser testing. # dev and build ```bash npm run dev # Vite dev server for example/ npm run dev:test # Vite dev server for test/ — E2E 参数测试页 npm run build # tsup → dist/ ``` ## 产物格式 `npm run build` 后 `dist/` 包含三种格式，通过 `package.json` 的 `exports` 自动选用： | 文件 | 格式 | 适用场景 | |------|------|----------| | `number-flip.mjs` | ESM | `import { Flip } from 'number-flip'`（Framer、Vite、Webpack 5 等） | | `number-flip.cjs` | CJS | `require('number-flip')` | | `index.js` | IIFE | `