Kappa / Timer

Simulation slot releases in

<script setup>
import { Timer } from "@dicehub/kappa/components/timer";
</script>

<template>
  <Timer.Root auto-start countdown :start-ms="65_000" :target-ms="0">
    <Timer.Area>
      <Timer.Item type="minutes" />
      <Timer.Separator />
      <Timer.Item type="seconds" />
    </Timer.Area>
    <Timer.Control>
      <Timer.ActionTrigger action="pause">Pause</Timer.ActionTrigger>
      <Timer.ActionTrigger action="resume">Resume</Timer.ActionTrigger>
      <Timer.ActionTrigger action="restart">Restart</Timer.ActionTrigger>
    </Timer.Control>
  </Timer.Root>
</template>

Installation

Timer is part of the main Kappa package. Ark UI owns its clock, actions, completion state, and timer semantics.

Barrel

import {
  Timer,
  TimerActionTrigger,
  TimerArea,
  TimerItem,
  TimerRoot,
} from "@dicehub/kappa";

Granular

import {
  Timer,
  TimerActionTrigger,
  TimerArea,
  TimerItem,
  TimerRoot,
} from "@dicehub/kappa/components/timer";

Usage

Set countdown for a decreasing timer. Set startMs andtargetMs in milliseconds. Action triggers hide when their action is not valid.

Use elapsed timers for operations, sessions, and run duration.
Use countdown timers for deadlines and time-limited resources.
Use interval only as often as the visible precision requires.

Composition

Typical part hierarchy

Timer.Root
├── Timer.Area
│   ├── Timer.Item
│   ├── Timer.Separator
│   └── Timer.Item
├── Timer.Control
│   └── Timer.ActionTrigger
└── Timer.Context (optional)

Ark UI controls elapsed time, formatted units, available actions, ticks, and completion. Kappa provides the compact display, sizes, controls, and value-change motion.

Examples

Elapsed Time

Start at zero and provide a target when the timer must complete at a fixed duration.

Elapsed solver time

<script setup>
import { Timer } from "@dicehub/kappa/components/timer";
</script>

<template>
  <Timer.Root :target-ms="3_600_000">
    <Timer.Area>
      <Timer.Item type="hours" />
      <Timer.Separator />
      <Timer.Item type="minutes" />
      <Timer.Separator />
      <Timer.Item type="seconds" />
    </Timer.Area>
    <Timer.Control>
      <Timer.ActionTrigger action="start">Start</Timer.ActionTrigger>
      <Timer.ActionTrigger action="pause">Pause</Timer.ActionTrigger>
      <Timer.ActionTrigger action="resume">Resume</Timer.ActionTrigger>
      <Timer.ActionTrigger action="reset">Reset</Timer.ActionTrigger>
    </Timer.Control>
  </Timer.Root>
</template>

Countdown

The complete event fires when the value reaches the target.

Automatic stop

Ready

<script setup>
import { Timer } from "@dicehub/kappa/components/timer";
import { ref } from "vue";

const complete = ref(false);
</script>

<template>
  <Timer.Root
    countdown
    :start-ms="15_000"
    :target-ms="0"
    @complete="complete = true"
  >
    <Timer.Area>
      <Timer.Item type="minutes" />
      <Timer.Separator />
      <Timer.Item type="seconds" />
    </Timer.Area>
    <Timer.Control>
      <Timer.ActionTrigger action="start">Start</Timer.ActionTrigger>
      <Timer.ActionTrigger action="pause">Pause</Timer.ActionTrigger>
      <Timer.ActionTrigger action="resume">Resume</Timer.ActionTrigger>
      <Timer.ActionTrigger action="restart">Restart</Timer.ActionTrigger>
      <Timer.ActionTrigger action="reset">Reset</Timer.ActionTrigger>
    </Timer.Control>
    <output aria-live="polite">{{ complete ? "Countdown complete" : "Ready" }}</output>
  </Timer.Root>
</template>

Milliseconds

Use a shorter interval for short operations. Disable animation on fast-changing units to keep the value clear.

Short operation

000

<script setup>
import { Timer } from "@dicehub/kappa/components/timer";
</script>

<template>
  <Timer.Root auto-start :interval="100" :target-ms="10_000">
    <Timer.Area>
      <Timer.Item type="seconds" />
      <Timer.Separator>.</Timer.Separator>
      <Timer.Item type="milliseconds" :animate="false" />
    </Timer.Area>
    <Timer.Control>
      <Timer.ActionTrigger action="start">Start</Timer.ActionTrigger>
      <Timer.ActionTrigger action="pause">Pause</Timer.ActionTrigger>
      <Timer.ActionTrigger action="resume">Resume</Timer.ActionTrigger>
      <Timer.ActionTrigger action="reset">Reset</Timer.ActionTrigger>
    </Timer.Control>
  </Timer.Root>
</template>

Sizes

Use the small size in dense controls and the large size for a primary elapsed-time display.

Small

Base

Large

<template>
  <Timer.Root size="sm" :start-ms="3_723_000">…</Timer.Root>
  <Timer.Root size="base" :start-ms="3_723_000">…</Timer.Root>
  <Timer.Root size="lg" :start-ms="3_723_000">…</Timer.Root>
</template>

Changed units use a short number-pop transition inspired byTransitions.dev. Set animate=false on an item when rapid changes would be distracting. Kappa disables the effect when the user requests reduced motion.

Accessibility

Area exposes an atomic timer region with a formatted accessible label.
Separators are hidden from assistive technology.
Action triggers are native buttons and hide when their action is unavailable.
Use a separate polite status only when completion needs an announcement.
Do not use a short interval unless the additional precision is useful.

API Reference

Timer.Root

Prop	Type	Default	Description
`autoStart`	`boolean`	`false`	Starts the timer when it mounts.
`countdown`	`boolean`	`false`	Decrements time instead of increasing it.
`startMs`	`number`	`0`	Initial time in milliseconds.
`targetMs`	`number`	`—`	Completion boundary in milliseconds.
`interval`	`number`	`1000`	Update interval in milliseconds.
`size`	`"sm" \| "base" \| "lg"`	`"base"`	Visual size of the display and controls.
`translations`	`IntlTranslations`	`Ark defaults`	Customizes the accessible timer label.
`id / ids`	`string / partial ID map`	`generated`	Overrides machine and part identifiers.
`asChild`	`boolean`	`false`	Merges root behavior into the direct child.

Timer.Item

Prop	Type	Default	Description
`type`	`"days" \| "hours" \| "minutes" \| "seconds" \| "milliseconds"`	`—`	Time unit rendered by the item.
`animate`	`boolean`	`true`	Runs the Kappa number-pop transition when the formatted value changes.
`asChild`	`boolean`	`false`	Merges item behavior into the direct child.

Parts

Part	Element	Description
`Timer.Area`	`div`	Atomic timer region and formatted value container.
`Timer.Item`	`div`	One formatted time unit with optional number-pop motion.
`Timer.Separator`	`div`	Hidden-from-assistive-technology separator; defaults to a colon.
`Timer.Control`	`div`	Groups timer action triggers.
`Timer.ActionTrigger`	`button`	Starts, pauses, resumes, resets, or restarts the timer.
`Timer.Context`	`renderless`	Exposes timer state and imperative actions to a slot.

Events

Event	Payload	Description
`tick`	`TickDetails`	Reports the current milliseconds and formatted time at each interval.
`complete`	`void`	Fires when the timer reaches its target.

Exports

Export	Description
`Timer`	Styled compound Timer component.
`TimerRoot / TimerRootProvider`	Direct root and external-machine provider components.
`TimerArea / TimerItem / TimerSeparator`	Granular formatted-time parts.
`TimerControl / TimerActionTrigger`	Granular timer controls.
`TimerContext`	Renderless access to current state and actions.
`useTimer / useTimerContext`	Ark UI composition functions.
`TimerProps / TimerSlots / TickDetails`	Public TypeScript contracts.