https://github.com/binlabs/digit-spinner
A lightweight web component for odometer-style digit spinners and simple numeric counters.
https://github.com/binlabs/digit-spinner
counter lit odometer typescript web-component
Last synced: 5 months ago
JSON representation
A lightweight web component for odometer-style digit spinners and simple numeric counters.
- Host: GitHub
- URL: https://github.com/binlabs/digit-spinner
- Owner: binlabs
- License: mit
- Created: 2025-05-27T19:32:09.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-24T13:58:46.000Z (about 1 year ago)
- Last Synced: 2025-06-24T14:44:20.194Z (about 1 year ago)
- Topics: counter, lit, odometer, typescript, web-component
- Language: TypeScript
- Homepage: https://binlabs.github.io/digit-spinner/
- Size: 146 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Digit Spinner
A smooth, animated odometer-like web component built with Lit. Display numbers with beautiful spinning digit animations that transition seamlessly between values. See the [documentation](https://binlabs.github.io/digit-spinner/) for more details and a [live demo](https://binlabs.github.io/digit-spinner/playground/).
## Features
- 🎯 **Smooth Animations**: Fluid digit transitions with customizable easing
- 🔄 **Multi-Direction**: Can animate up, down, or the shortest path
- 🎨 **Customizable Styling**: CSS custom properties for complete visual control
- 📱 **Lightweight**: Built with Lit for optimal performance
- 🔢 **Flexible Formatting**: Support for leading zeros and minimum digit counts
- 🎪 **Rich Events**: Detailed animation lifecycle events
## Installation
```bash
npm install digit-spinner
```
## Basic Usage
```html
```
## API Reference
### ``
The main component that displays animated numbers with spinning digit transitions.
#### Properties
| Property | Attribute | Type | Default | Description |
| ----------- | ------------ | -------- | ---------------------------------- | --------------------------------------------------------- |
| `value` | `value` | `number` | `0` | The numeric value to display |
| `direction` | `direction` | `string` | `'forward'` | Animation direction: 'forward', 'backward', or 'shortest' |
| `duration` | `duration` | `number` | `200` | Animation duration in milliseconds |
| `easing` | `easing` | `string` | `'cubic-bezier(0.83, 0, 0.17, 1)'` | Animation easing function |
| `minDigits` | `min-digits` | `number` | `0` | Minimum number of digits (pads with leading zeros) |
#### Methods
| Method | Parameters | Description |
| ----------------- | ----------------- | ------------------------------------------ |
| `increment(num?)` | `num: number = 1` | Increase the value by the specified amount |
| `decrement(num?)` | `num: number = 1` | Decrease the value by the specified amount |
#### Events
The `` element emits the following events:
| Event | Properties | Description |
| ------------------ | ----------------------------------------------- | --------------------------------------------- |
| `digit-flip-start` | `{from: number, to: number}` | Fired when digit animation begins |
| `digit-flip-end` | `{from: number, to: number}` | Fired when digit animation completes |
| `digit-wrap` | `{from: number, to: number, direction: string}` | Fired when digit wraps from 9 to 0, or 0 to 9 |
#### Examples
```html
+
-
```
## Styling
Customize the appearance using [CSS custom properties](https://binlabs.github.io/digit-spinner/api/#digit-spinner-css-custom-properties):
```css
digit-spinner {
--digit-font-size: 2rem;
--digit-font: 'Courier New', monospace;
--digit-color: #333;
--digit-background-color: #f0f0f0;
}
```
### CSS Parts
Internal elements can also be styled using [CSS parts](https://binlabs.github.io/digit-spinner/api/#digit-spinner-css-shadow-parts):
```css
digit-spinner::part(container) {
/* Style the main container */
}
digit-spinner::part(digit-wrapper) {
/* Style individual digit wrappers */
}
digit-spinner::part(digit) {
/* Style digit elements */
border-radius: 4px;
padding: 8px;
}
```
## Advanced Examples
### Event Handling
In this example, we listen for the `digit-flip-start` event to log the digit that has begun flipping.
```html
document
.getElementById('event-demo')
.addEventListener('digit-flip-start', (e) => {
const origin = e.composedPath()[0]; // Reference to the digit
console.log(
`Digit ${origin} has started flipping from ${e.from} to ${e.to}`
);
});
```
### Custom Styled Odometer
```html
digit-spinner {
--digit-font-size: 2rem;
--digit-font: 'Courier New', monospace;
--digit-color: #333;
--digit-background-color: #f0f0f0;
}
```
## Browser Support
This component uses modern web standards and requires:
- ES2020+ support
- Custom Elements v1
- CSS Custom Properties
- Web Animations API
Supports all modern browsers including Chrome 80+, Firefox 75+, Safari 13.1+, and Edge 80+.
## Development
The component is built with:
- [Lit](https://lit.dev/) - Efficient web component library
- [@lit-labs/motion](https://www.npmjs.com/package/@lit-labs/motion) - Animation utilities
- TypeScript - Type safety and better development experience
## Credits
- Animation mechanics inspired by the @lit-labs/motion [Carousel Transition example](https://lit.dev/playground/#sample=examples/motion-carousel)
- Project was started using [lit-element-starter-ts](https://github.com/lit/lit-element-starter-ts)
## License
MIT License - see LICENSE file for details.
## Contributing
Contributions are welcome! Please feel free to submit issues and pull requests.