KQ-1196 · GEARED/PEN
Geared Pen
An inline loader drawn by a geared pen: a wheel rolls inside a toothed ring and its pen traces a hypotrochoid with as many lobes as the ratio, the wheel's own turn accumulated rather than computed so a changing ratio never makes the pen jump. Free-running, a frame loop writes the geometry into motion values, the trail fades behind the pen in tapered chunks, and the ratio drifts on a slow sine so the rosette precesses and never quite repeats; given progress, the ratio holds and the figure is drawn solid on springs.glide, closing at 1 as the pen lifts. The glyph is a button: drag around its centre and the wheel follows the pointer's angle 1:1, a free wheel keeps the throw and eases back to its pace while a determinate one glides home on springs.glide with the release velocity, and arrow keys turn it a notch (springs.snap) while Enter or Space spins it round.
rendering · q3 meter report · turn the wheel
Install
One command — the source lands in your repo. Or copy it from the Code tab.
$ pnpm dlx shadcn@latest add @kinetiq/geared-pen
Props
- label
- string
- default "Loading"
- What is loading. Shown beside the glyph and the loader's accessible name: the status's, or the progressbar's when progress is given.
- hideLabel
- boolean
- default false
- Keep the label for assistive technology only, for a glyph inline in a sentence or a row.
- size
- number
- default 24
- The glyph's box in px, crisp from 16 to 64: detail simplifies below 40 and below 24 so it still reads at text size.
- speed
- number
- default 1
- How fast the wheel goes round, 0.5 to 2.
- ratio
- number
- default 5
- The ring's size over the wheel's, 2 to 9: the figure's lobes. Half steps weave two orbits before the figure closes.
- trail
- number
- default 0.6
- How long the fading trail is, 0 (a short comet) to 1 (three orbits), and the length of the comet a hand's turn leaves on a determinate figure.
- ink
- "cobalt" | "rose" | "lime"
- default "cobalt"
- The pen's colour: the theme's bright accent, or the danger and success tokens' lightness and chroma at the ink's own hue, so the thin line keeps its contrast in both themes.
- progress
- number
- default —
- Determinate, 0 to 1: how much of the closed figure is drawn, solid, with the pen at its head. Without it the pen never stops.
- onTurn
- () => void
- default —
- The wheel was turned by hand, tap or key.
- disabled
- boolean
- default false
- Keep drawing, but refuse the hand: the glyph is drawn as a picture with no button, for loaders that should not be a tab stop.
- className
- string
- default —
- Classes for the inline root; text size set here reaches the label.
| Prop | Type | Default | Description |
|---|---|---|---|
| label | string | "Loading" | What is loading. Shown beside the glyph and the loader's accessible name: the status's, or the progressbar's when progress is given. |
| hideLabel | boolean | false | Keep the label for assistive technology only, for a glyph inline in a sentence or a row. |
| size | number | 24 | The glyph's box in px, crisp from 16 to 64: detail simplifies below 40 and below 24 so it still reads at text size. |
| speed | number | 1 | How fast the wheel goes round, 0.5 to 2. |
| ratio | number | 5 | The ring's size over the wheel's, 2 to 9: the figure's lobes. Half steps weave two orbits before the figure closes. |
| trail | number | 0.6 | How long the fading trail is, 0 (a short comet) to 1 (three orbits), and the length of the comet a hand's turn leaves on a determinate figure. |
| ink | "cobalt" | "rose" | "lime" | "cobalt" | The pen's colour: the theme's bright accent, or the danger and success tokens' lightness and chroma at the ink's own hue, so the thin line keeps its contrast in both themes. |
| progress | number | — | Determinate, 0 to 1: how much of the closed figure is drawn, solid, with the pen at its head. Without it the pen never stops. |
| onTurn | () => void | — | The wheel was turned by hand, tap or key. |
| disabled | boolean | false | Keep drawing, but refuse the hand: the glyph is drawn as a picture with no button, for loaders that should not be a tab stop. |
| className | string | — | Classes for the inline root; text size set here reaches the label. |