https://github.com/delacrixmorgan/rollingnumbers
Rolling Numbers - Odometer Scrolling Effect TextView 🎰
https://github.com/delacrixmorgan/rollingnumbers
android android-ui currency desktop ios ios-ui kmp kotlin levenshtein-distance library text-animation textview wasm
Last synced: about 1 month ago
JSON representation
Rolling Numbers - Odometer Scrolling Effect TextView 🎰
- Host: GitHub
- URL: https://github.com/delacrixmorgan/rollingnumbers
- Owner: delacrixmorgan
- License: gpl-3.0
- Created: 2025-08-13T18:57:25.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2026-04-09T17:01:12.000Z (3 months ago)
- Last Synced: 2026-04-09T18:28:38.139Z (3 months ago)
- Topics: android, android-ui, currency, desktop, ios, ios-ui, kmp, kotlin, levenshtein-distance, library, text-animation, textview, wasm
- Language: Kotlin
- Homepage:
- Size: 8.2 MB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
README
# Rolling Numbers - Odometer Scrolling Effect TextView 🎰
**RollingNumbers** is a Kotlin Multiplatform Compose library that animates text changes by rolling
individual characters vertically — just like a **odometer**, an **old school cash
register**, or those nostalgic **airport split-flap boards**.
Whether you’re showing stock prices, countdowns, money, or even flight numbers,
RollingNumbers makes every change feel *satisfyingly alive* with Levenshtein distance effect!
It also comes with a separate ready-to-use `CurrencyRollingNumbers` for **beautifully animated,
locale-friendly money displays**.
| Integer | Decimal |
|-----------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------|
| | |
| Currency | Alphanumeric |
|-----------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------|
| | |
## ✨ Features
- 🔢 **Animate anything** — numbers, letters, symbols, emojis… if it’s a character, it can roll.
- 💰 **Built-in currency mode** — grouping separators, decimal points, and currency symbol
placement (front or back) out of the box.
- ↕️ **Smart direction detection** — rolls up when values go up, down when they drop.
- 🎯 **Custom character sets** — hex digits, flight numbers, scoreboard letters… your animation path,
your rules.
- 🎨 **Fully styleable** — integrates seamlessly with Compose’s `TextStyle`.
- ⚡ **Adjustable speed** — from dramatic slow rolls to rapid-fire flicks.
- 🪶 **Lightweight & clean** — minimal dependencies, easy to drop into any project.
- 🌍 **KMP ready** — works across Android, iOS, Desktop and WASM.
- 🧠 **Levenshtein-powered animation** — calculates the smoothest, shortest scroll path between
states.
## 🕹️ Fun Facts
1. Inspired by [Robinhood Ticker library](https://github.com/robinhood/ticker) — but built for the
modern Kotlin Multiplatform Compose world.
2. Fully **Kotlin Multiplatform** — the same rolling goodness on Android, iOS and Desktop.
3. Comes with **two ready-made components**:
- `RollingNumbers` for any kind of text
- `CurrencyRollingNumbers` for perfectly formatted animated amounts with currency.
4. Supports **alphanumeric** and custom sets — perfect for flight numbers, scoreboard codes, or
creative displays.
5. **Optimized for performance** while still feeling smooth and fun to watch.
## 📦 Installation
Add the dependency in your `build.gradle.kts`:
### Step 1
Add the mavenCentral repository to your `settings.gradle.kts` file:
```groovy
dependencyResolutionManagement {
repositories {
mavenCentral()
}
}
```
### Step 2
Add the dependency:
```groovy
dependencies {
implementation "com.dontsaybojio:rollingnumbers:X.X.X"
}
```
## 🚀 Usage
### Numbers
```kotlin
RollingNumbers(
text = amount,
characterLists = listOf(Utils.provideNumberString()),
animationDuration = DefaultAnimationDuration.Default.duration,
)
```
### Currency
```kotlin
CurrencyRollingNumbers(
amount = amount,
characterLists = listOf(Utils.provideNumberString()),
animationDuration = DefaultAnimationDuration.Default.duration,
)
```
### Alphanumeric
```kotlin
RollingNumbers(
text = text,
characterLists = Utils.provideAlphanumericList(),
animationDuration = DefaultAnimationDuration.Slow.duration,
)
```
## 📄 API Reference
### `RollingNumbers`
| Parameter | Type | Default | Description |
|----------------------|----------------------|---------------------------------------------|-------------------------------------------------------|
| `text` | `String` | **required** | The text to display and animate. |
| `modifier` | `Modifier` | `Modifier` | Compose modifier for layout/styling. |
| `characterLists` | `List` | `listOf(Utils.provideNumberString())` | List of character sequences defining animation paths. |
| `animationDuration` | `Int` | `DefaultAnimationDuration.Default.duration` | Duration of the scroll animation in milliseconds. |
| `textStyle` | `TextStyle` | `LocalTextStyle.current` | Style applied to the text. |
| `scrollingDirection` | `ScrollingDirection` | `Any` | Force scroll direction: `Up`, `Down`, or `Any`. |
| `animateChanges` | `Boolean` | `true` | Whether to animate changes or update instantly. |
### `CurrencyRollingNumbers`
| Parameter | Type | Default | Description |
|----------------------------------|----------------|---------------------------------------------|-----------------------------------------------------------|
| `amount` | `Double` | **required** | Target amount to display. |
| `modifier` | `Modifier` | `Modifier` | Compose modifier for layout/styling. |
| `characterLists` | `List` | `listOf(Utils.provideNumberString())` | List of character sequences defining animation paths. |
| `animationDuration` | `Int` | `DefaultAnimationDuration.Default.duration` | Duration of the scroll animation in milliseconds. |
| `textStyle` | `TextStyle` | `LocalTextStyle.current` | Style applied to the text. |
| `positiveSignedSymbolColor` | `Color` | textStyle's colour | Positive signed symbol colour. |
| `negativeSignedSymbolColor` | `Color` | textStyle's colour | Negative signed symbol colour. |
| `animateChanges` | `Boolean` | `true` | Whether to animate changes or update instantly. |
| `decimals` | `Int` | `2` | Number of decimal places to format. |
| `currencySymbol` | `String` | `"$"` | Currency symbol. |
| `spacingInBetweenCurrencySymbol` | `Dp` | `8.dp` | Spacing in dp between currency symbol and RollingNumbers. |
| `spacingInBetweenSignedSymbol` | `Dp` | `8.dp` | Spacing in dp between signed symbol and RollingNumbers |
| `showPositiveSignedSymbol` | Boolean | false | Show signed symbol for positive amount |
| `isCurrencySymbolInFront` | `Boolean` | Locale preference | Whether the currency symbol appears before the number. |
| `decimalSeparator` | `Char` | Locale preference | Decimal separator character. |
| `groupingSeparator` | `Char` | Locale preference | Thousands separator character. |
### `DefaultAnimationDuration in ms`
| Attribute | Type | Value |
|--------------------|-------|-------|
| `Slow` | `Int` | 3_500 |
| `Medium (Default)` | `Int` | 2_000 |
| `Fast` | `Int` | 1_000 |
## 🔧 Developer Notes
The library uses:
• Levenshtein distance to determine minimal scrolling changes between the current and target text.
• `AnimatedCharacterColumn` for per-character scroll animation.
• `clipToBounds()` to keep animations inside their columns.
• Multiple Character Sets:
You can pass multiple strings in characterLists if you want certain characters to scroll
independently (e.g., digits and symbols in different sequences).
• Custom Direction Control:
For number-based animations, use `ScrollingDirection.Up` or `ScrollingDirection.Down` to force a
scroll direction or it can be `ScrollingDirection.Any` for the nearest distance.
## 💡 Contributing
Pull requests are welcome!
If you find a bug or have a feature request, please open an issue on GitHub.
## ❤️ Acknowledgements
- [Robinhood Ticker](https://github.com/robinhood/ticker)