CharFlow

Lightweight animated alphanumeric text for license plates, codes, and flowing paragraphs.

Digits and letters roll through their alphabet on change; inserts and deletes slide in and out. Built as a web component with an optional React wrapper.

Install

npm install char-flow

Web component

Import the element entry to register <char-flow>:

<script type="module">
  import 'char-flow/element'
</script>

<char-flow value="G-123-BB" preset="plate"></char-flow>

Or use the main entry (registers the element and re-exports helpers):

import 'char-flow'

Attributes

| Attribute | Default | Description | |---|---|---| | value | "" | Text to display | | preset | alnum | plate (uppercase, tabular) or alnum | | animated | true | Set to false to disable motion | | direction | auto | auto picks the shortest wheel path, forward counts up, backward counts down | | roll | auto | auto matches path direction, up / down force the on-screen scroll (path still follows direction) |

Use direction for which wheel route to take and roll for how it should look. A clock ticking forward with digits rolling down:

<char-flow value="12:32" direction="forward" roll="down"></char-flow>

Animations respect prefers-reduced-motion.

Styling

The component uses shadow DOM. Target the host or the exposed part:

char-flow.plate {
  font-size: 2.5rem;
  font-weight: 700;
  letter-spacing: 0.06em;
}

char-flow::part(root) {
  /* inner shell */
}

Timing can be adjusted from JavaScript:

const el = document.querySelector('char-flow')
el.spinTiming = { duration: 520, easing: 'cubic-bezier(0.32, 0.72, 0, 1)' }
el.slideTiming = { duration: 340 }

React

Register the element first, then use the wrapper:

import 'char-flow/element'
import { CharFlow } from 'char-flow/react'

export function Plate({ value }: { value: string }) {
  return <CharFlow value={value} preset="plate" className="plate" />
}

export function Clock({ value }: { value: string }) {
  return <CharFlow value={value} preset="alnum" direction="forward" roll="down" />
}

React is an optional peer dependency (>=18).

Low-level API

The main entry also exports diffing, classification, and stack-planning helpers:

import { diff, classify, planFor, applyRoll } from 'char-flow'

diff('ABC-100', 'ABC-9')
classify('G')

// inspect or customise a digit roll before rendering
const plan = planFor(
  { key: 'm', char: '3', anim: 'wheel-digit', fromChar: '2' },
  'forward',
  'down',
)

Demo

npm run demo

Opens a local demo at http://localhost:3000/demo/.

Development

npm install
npm run build
npm run typecheck

License

MIT