KQ-1191 · HOURGLASS/TURN
Hourglass Turn
An inline loader drawn as a small hourglass: sand runs from the top bulb onto a growing pile as a falling thread, conserved as drawn area so the top's level races where the bulb narrows, and when the top is empty the glass rests a beat and turns itself over on the snap spring while the sand rides the turn and slumps onto the neck. Drag it sideways and it follows the pointer, the thread breaks, and a release past a quarter turn completes the half turn with the release velocity so the sand stays where it was; with progress the pile is the progress and a turn by hand is a full tumble on glide. It is a real button — Enter or Space turns it — beside a status or progressbar label, and the landing thocks only when the visitor turned it.
backing up · drag the glass to turn it
Install
One command — the source lands in your repo. Or copy it from the Code tab.
$ pnpm dlx shadcn@latest add @kinetiq/hourglass-turn
Props
- label
- string
- default —
- Visible text beside the glyph, and the loader's accessible name ("Loading" when omitted).
- hideLabel
- boolean
- default false
- Keep the label for assistive technology only.
- size
- number
- default 32
- The glyph's box in px, 16 to 64. Detail is chosen by size: posts and a pile shadow from 24, falling grains from 32, a glass highlight from 40.
- speed
- number
- default 1
- How fast the sand runs (3.2 s a run at 1) and how long it rests before turning, 0.5 to 2.
- sand
- "sand" | "rose" | "mint"
- default "sand"
- The sand's pigment, at a fixed lightness so it reads the same in both themes.
- progress
- number
- default —
- Determinate share run through, 0 to 1: the pile holds that share and the sand runs to each new value at the glass's own rate. Omit for a glass that keeps turning.
- sound
- boolean
- default false
- Play a thock when the glass lands after the visitor turned it (and a quiet one when a short drag rocks back). The self-turn is silent.
- disabled
- boolean
- default false
- Keeps running, but cannot be turned by hand or key.
- className
- string
- default —
- Classes for the inline root; the label inherits its font size and colour.
| Prop | Type | Default | Description |
|---|---|---|---|
| label | string | — | Visible text beside the glyph, and the loader's accessible name ("Loading" when omitted). |
| hideLabel | boolean | false | Keep the label for assistive technology only. |
| size | number | 32 | The glyph's box in px, 16 to 64. Detail is chosen by size: posts and a pile shadow from 24, falling grains from 32, a glass highlight from 40. |
| speed | number | 1 | How fast the sand runs (3.2 s a run at 1) and how long it rests before turning, 0.5 to 2. |
| sand | "sand" | "rose" | "mint" | "sand" | The sand's pigment, at a fixed lightness so it reads the same in both themes. |
| progress | number | — | Determinate share run through, 0 to 1: the pile holds that share and the sand runs to each new value at the glass's own rate. Omit for a glass that keeps turning. |
| sound | boolean | false | Play a thock when the glass lands after the visitor turned it (and a quiet one when a short drag rocks back). The self-turn is silent. |
| disabled | boolean | false | Keeps running, but cannot be turned by hand or key. |
| className | string | — | Classes for the inline root; the label inherits its font size and colour. |