CronBuilder

Code

import { CronBuilder } from "@fadymondy/nasaq/web";import { useState } from "react";export function Trigger() {  const [cron, setCron] = useState("0 9 * * 1-5");  const [zone, setZone] = useState("Asia/Riyadh");  return <CronBuilder value={cron} onValueChange={(v) => setCron(v)} timeZone={zone} onTimeZoneChange={setZone} />;}

Workflow · beta

Live examples and controls: CronBuilder in the lab.

InstallCopy Anchor Link

npx shadcn@latest add https://docs.nasaqui.com/r/cron-builder.json

Pick "every weekday at 09:00" from simple settings, or type the cron expression itself. Either way the builder says the schedule in words (English or Arabic), names the field that is wrong when the expression does not parse, and lists the next runs in the time zone you chose, so nobody has to trust their own reading of 0 9 * * 1-5. The value is always the cron string. The parser is built in (no cron library): five fields, *, lists, ranges, steps, month and day names, @daily style macros, daylight saving gaps skipped. CronScheduleList is the companion list of saved schedules.

When to useCopy Anchor Link

• A trigger step in a workflow, a backup or report schedule, any recurring job the user configures.
• A settings page listing schedules with their last outcome (CronScheduleList).

When not to useCopy Anchor Link

• Picking a single date and time: use date-picker. Calendar-style booking: use scheduler.
• Second-level or Quartz seven-field expressions: only the five standard fields are supported.

ImportCopy Anchor Link

import { CronBuilder, CronScheduleList } from "@fadymondy/nasaq/web";
// inside this monorepo: "@nasaq/web"

Quick startCopy Anchor Link

import { CronBuilder } from "@fadymondy/nasaq/web";
import { useState } from "react";

export function Trigger() {
  const [cron, setCron] = useState("0 9 * * 1-5");
  const [zone, setZone] = useState("Asia/Riyadh");
  return <CronBuilder value={cron} onValueChange={(v) => setCron(v)} timeZone={zone} onTimeZoneChange={setZone} />;
}

onValueChange fires on every keystroke with valid, so a half-typed expression is still the value. Check valid (or call isValidCron) before you save.

AnatomyCopy Anchor Link

CronBuilder                     data-slot="cron-builder"
├─ presets                      Buttons with aria-pressed
├─ Tabs: Simple | Cron expression
│  ├─ simple: repeat, every N, minute, time, weekdays (ToggleGroup), day of month
│  └─ cron: monospace Input, hint, alert with the failing field
├─ summary                      data-slot="cron-summary", aria-live polite
├─ time zone Select
└─ next runs                    data-slot="cron-next-runs"

CronScheduleList                data-slot="cron-schedule-list"
└─ row                          Switch, name and words, last run Status, next run, run now / edit / delete

APICopy Anchor Link

CronBuilderCopy Anchor Link

Every div prop except children, plus:

CronScheduleListCopy Anchor Link

HelpersCopy Anchor Link

parseCron(expr) returns { ok: true, value } or { ok: false, error: { code, field, token } }. nextRuns(expr, { from, count, timeZone }) returns Dates. describeCron(expr, "en" | "ar") returns a sentence or null. simpleToCron and cronToSimple convert the simple form. isValidCron, isValidTimeZone and DEFAULT_CRON_PRESETS are exported too.

ExamplesCopy Anchor Link

Saved schedules with statuses:

import { CronScheduleList } from "@fadymondy/nasaq/web";

export const Schedules = () => (
  <CronScheduleList
    schedules={[
      { id: "1", name: "Weekly report", cron: "0 9 * * 1", timeZone: "Asia/Riyadh", enabled: true, lastRun: { at: Date.now() - 3600_000, status: "ok" } },
      { id: "2", name: "Sync CRM", cron: "*/15 * * * *", enabled: true, lastRun: { at: Date.now() - 900_000, status: "failed" } },
    ]}
    onToggle={async () => {}}
    onRunNow={async () => {}}
  />
);

AccessibilityCopy Anchor Link

The summary is a polite live region. A wrong expression is announced with role="alert" and aria-invalid. Weekday toggles carry the full day name. Schedule status is an icon plus a word, never colour alone. Localise label and any custom labels.

RTL & i18nCopy Anchor Link

• Cron text, time zone names and times stay left-to-right (dir="ltr"); the sentence around them follows the language.
• Digits are Latin, like the rest of Nasaq. Arabic plurals (دقيقتين، 5 دقائق، 15 دقيقة) are handled.
• The weekday toggles run in reading order, so Sunday sits at the start in both languages.

Styling & tokensCopy Anchor Link

• Uses --nq-surface-soft, --nq-danger-text, border and card tokens. Extend with className; never pass raw hex.

Do / Don'tCopy Anchor Link

• Do show the time zone the schedule runs in; a schedule without one is a bug waiting for daylight saving.
• Do show the next runs before saving.
• Don't accept a value without checking valid.

RelatedCopy Anchor Link

• workflow-canvas
• backup-manager
• run-history

LabCopy Anchor Link

https://docs.nasaqui.com/?path=/docs/components-workflow-cron-builder--docs