Rate-limit hourglass
Falling-sand hourglass that counts down to a usage reset; the remaining time is derived from the sand left in the top chamber.
Your data
Set duration to the seconds left until your limit resets, and again whenever you learn a new value; nothing else is shown. See Your data.
Playground
Change a prop and the component updates. Props marked live animate to the new value; the others rebuild the element.
<PxHourglass duration={30} />Installation
pnpm dlx shadcn@latest add @lumesec/px-hourglassFirst timeRegister the @lumesec registry once, or install by URL
Adds @lumesec to your components.json:
pnpm dlx shadcn@latest registry add @lumesec=https://elements.lumesec.ai/r/{name}.jsonOr skip the setup and install by URL:
npx shadcn@latest add https://elements.lumesec.ai/r/px-hourglass.jsonUsage
import { PxHourglass } from "@/components/lumesec/px-hourglass";
export function Example() {
return (
<PxHourglass duration={30} />
);
}Behaviour
A real falling-sand simulation counts down to the next usage reset. Grains pile up, slide off each other and squeeze through the neck one at a time; the timer is how much sand is left.
API reference
Attributes
durationReact propdurationTypenumberDefault30Countdown length in seconds for a full top chamber; a missing, invalid or non-positive value uses 30. A later change re-times the sand left in the top chamber to run out in that many seconds.
Events
Events bubble and cross the shadow boundary unless the description says otherwise.
flipReact proponFlipDetail{}Fires after the hourglass has turned over.
resetReact proponResetDetail{}Fires once when the top chamber runs empty, meaning the limit has reset.
Methods
Call them on the element, for example through a React ref.
flip()Turns the hourglass over so the sand runs back. Ignored while a flip is animating.
Properties
durationTypenumberCountdown length in seconds; reflects the duration attribute, 30 when it is missing, invalid or not positive.
Keyboard
| Keys | Action |
|---|---|
| Enter / Space (on the glass) | Flip the hourglass. |
Accessibility
- The glass is focusable (
tabindex="0") withrole="button"andaria-label="Flip the hourglass". - A native "Flip" button performs the same action.
- The countdown is plain text. The status line above it ("Usage resets in", "Limit reset · flip to start") is an
aria-live="polite"region. The canvas sits inside the glass button. - Reduced motion: the flip happens instantly without the rotation, text swaps without the roll and the completion sparks are skipped; the sand simulation still runs.
Theming
The element reads your shadcn theme tokens through its shadow root, so light and dark follow your theme. The accent comes from --lumesec. See Theming.
This component reads --foreground, --lumesec, --lumesec-success and --muted-foreground.
To restyle only LumeSec elements, set the matching --ui-* overrides: --ui-accent, --ui-fg, --ui-muted and --ui-ok.
Notes
- The host gets a
data-doneattribute while the top chamber is empty, which turns the time green; it is cleared on the next flip. - Flipping part-way through inverts the current sand, so the remaining time becomes the elapsed time.
- The sand keeps time from the clock: after the element was off screen or the tab was hidden, it runs fast until it has caught up. Once the top chamber is empty and the sand has settled, the element stops drawing until the next flip.
- The glass canvas is a fixed 120 by 168px.
Related
Was this page helpful?