PomodoroCard

Code

import { BreakLockScreen, PomodoroCard, usePomodoro } from "@fadymondy/nasaq/web";export function Focus() {  const pomodoro = usePomodoro({ onEvent: (event) => api.saveSession(event) });  return (    <>      <PomodoroCard pomodoro={pomodoro} task={{ id: "t1", title: "Write the report" }} />      <BreakLockScreen        open={pomodoro.onBreak}        phase={pomodoro.phase === "longBreak" ? "longBreak" : "shortBreak"}        seconds={pomodoro.seconds}        fraction={pomodoro.fraction}        cycle={pomodoro.cycle}        cycles={pomodoro.cycles}        onPostpone={(minutes) => pomodoro.postpone(minutes * 60_000)}        onSkip={pomodoro.skip}      />    </>  );}

Productivity · beta

Live examples and controls: PomodoroCard in the lab.

InstallCopy Anchor Link

npx shadcn@latest add https://docs.nasaqui.com/r/pomodoro.json

Focus in sessions, rest in between. usePomodoro runs the classic cycle (25 minutes of focus, a 5 minute break, and a 15 minute break after every fourth session) and returns one controller. PomodoroCard shows it: cycle dots, the timer ring with the phase inside, start, pause, skip and stop, the task the session is for, and today against a daily goal. BreakLockScreen covers the page during a break with the countdown and a stretch or water suggestion.

When to useCopy Anchor Link

• A focus timer in a health, wellbeing or productivity product.
• Forcing a real rest: the break screen traps focus so it is hard to click past.

When not to useCopy Anchor Link

• Tracking billable hours: use TimeTracker.
• Locking the app for security: use LockScreen and IdleLock.
• A plain countdown: use useCountdownTimer.

ImportCopy Anchor Link

import { BreakLockScreen, PomodoroCard, usePomodoro } from "@fadymondy/nasaq/web";
// inside this monorepo: "@nasaq/web"

Quick startCopy Anchor Link

import { BreakLockScreen, PomodoroCard, usePomodoro } from "@fadymondy/nasaq/web";

export function Focus() {
  const pomodoro = usePomodoro({ onEvent: (event) => api.saveSession(event) });
  return (
    <>
      <PomodoroCard pomodoro={pomodoro} task={{ id: "t1", title: "Write the report" }} />
      <BreakLockScreen
        open={pomodoro.onBreak}
        phase={pomodoro.phase === "longBreak" ? "longBreak" : "shortBreak"}
        seconds={pomodoro.seconds}
        fraction={pomodoro.fraction}
        cycle={pomodoro.cycle}
        cycles={pomodoro.cycles}
        onPostpone={(minutes) => pomodoro.postpone(minutes * 60_000)}
        onSkip={pomodoro.skip}
      />
    </>
  );
}

AnatomyCopy Anchor Link

PomodoroCard                    data-slot="pomodoro-card", data-phase, data-status
├─ CycleDots                    sessions in the set
├─ TimerRing + TimerReadout     phase icon, mm:ss and the phase word
├─ Start / Pause, Skip, Stop
├─ task                         data-slot="pomodoro-task" (a picker when `tasks` is given)
└─ today                        data-slot="pomodoro-today", Progress against the daily goal
BreakLockScreen                 data-slot="break-lock-screen", data-phase, data-confirming
├─ title and message
├─ TimerRing + CycleDots
├─ suggestion                   data-slot="break-suggestion"
├─ Postpone, Skip break
└─ confirm                      data-slot="break-lock-confirm"

APICopy Anchor Link

usePomodoro(options): PomodoroControllerCopy Anchor Link

The controller has state, config, phase ("focus" \| "shortBreak" \| "longBreak"), status, cycle, cycles, completed, remainingMs, seconds, fraction (share left, 1 to 0), onBreak, and the actions start(), pause(), resume(), toggle(), skip(), stop(), postpone(ms).

Rules: a focus that ends counts as a session and starts the break at once. Skipping focus goes to a break without counting. After the last session in a set the break is long, and the set restarts after it. Postponing a break gives extra focus time that does not count as a new session; the break is owed again afterwards. stop() keeps today's count. Phases that start by themselves begin at the previous phase's end, so a late tick shortens nothing.

PomodoroCardCopy Anchor Link

BreakLockScreenCopy Anchor Link

ExamplesCopy Anchor Link

Persist across reloadsCopy Anchor Link

const saved = JSON.parse(localStorage.getItem("pomodoro") ?? "null") ?? undefined;
const pomodoro = usePomodoro({ initialState: saved, onStateChange: (s) => localStorage.setItem("pomodoro", JSON.stringify(s)) });

Auto-start everything, four-minute long breakCopy Anchor Link

usePomodoro({ config: { autoStartFocus: true, longBreakMs: 4 * 60_000 } });

ArabicCopy Anchor Link

<NasaqProvider locale="ar">
  <PomodoroCard pomodoro={pomodoro} />
</NasaqProvider>

AccessibilityCopy Anchor Link

• The break screen is a modal dialog: the page behind is inert, focus is trapped, outside clicks do nothing. Only onSkip after the confirmation, or your own open={false}, removes it.
• The card announces "Focus started" / "Break started" in a polite live region. The readout does not announce every second.
• The ring dashes when paused and each phase has its own icon and word: state is not conveyed by colour alone.
• prefers-reduced-motion stops the ring, fade and suggestion pulse.
• Localise labels for languages other than English and Arabic.

RTL & i18nCopy Anchor Link

• English and Arabic copy is built in. The timer is always left-to-right; Play and Skip icons mirror in RTL.
• Numbers use Western digits in both languages.

Styling & tokensCopy Anchor Link

Tokens only (bg-primary, stroke-nq-success, bg-nq-success-soft, bg-background). Target data-phase and data-status on the card and data-phase, data-confirming on the break screen. The screen sits at z-[100].

Do / Don'tCopy Anchor Link

• Do save sessions in onEvent, not by watching the controller.
• Do keep the break screen for real breaks; let people postpone and skip with a confirm rather than trapping them.
• Don't use the break screen for security locks; it is not authentication.
• Don't persist state created with speed other than 1.

RelatedCopy Anchor Link

• Countdown
• FocusStatus
• TimeTracker
• LockScreen

LabCopy Anchor Link

https://docs.nasaqui.com/?path=/docs/components-productivity-pomodoro-card--docs