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 for more details and a live demo.

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

npm install digit-spinner

Basic Usage

<script type="module" src="node_modules/digit-spinner/dist/index.js"></script>

<!-- Simple counter -->
<digit-spinner value="42"></digit-spinner>

API Reference

<digit-spinner>

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 <digit-spinner> 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

<!-- Basic usage -->
<digit-spinner value="123"></digit-spinner>

<!-- With leading zeros -->
<digit-spinner value="42" min-digits="4"></digit-spinner>
<!-- Shows: 0042 -->

<!-- Programmatic control -->
<digit-spinner id="counter" value="0" min-digits="3"></digit-spinner>
<button onclick="document.getElementById('counter').increment()">+</button>
<button onclick="document.getElementById('counter').decrement()">-</button>

Styling

Customize the appearance using CSS custom properties:

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:

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.

<digit-spinner id="event-demo" value="10"></digit-spinner>

<script>
  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}`
      );
    });
</script>

Custom Styled Odometer

<style>
  digit-spinner {
    --digit-font-size: 2rem;
    --digit-font: 'Courier New', monospace;
    --digit-color: #333;
    --digit-background-color: #f0f0f0;
  }
</style>

<digit-spinner value="88888"></digit-spinner>

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 - Efficient web component library
• @lit-labs/motion - Animation utilities
• TypeScript - Type safety and better development experience

Credits

• Animation mechanics inspired by the @lit-labs/motion Carousel Transition example
• Project was started using 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.