# Cron Picker

> A React cron expression builder: frequency tabs, weekday and day chips, a time, a sentence that reads the schedule back and the next runs.

- Type: React component (Inputs)
- Access: Pro (the source needs a Wingo UI Pro plan, see https://wingo-ui.com/pricing)
- Version: 1.0.0
- Install: `npx wingo-ui@latest add cron-picker`
- Docs: https://wingo-ui.com/components/cron-picker

## Interaction

Pick how often with the frequency tabs (arrow keys move between them; on a phone they show short names). Every few minutes and every few hours are a select in a sentence (a bottom sheet on phones), hourly adds the minute in a number field (arrows step, Shift steps by 5). Weekly shows seven day chips and monthly a 7-column grid of days 1 to 31: tap or press Space to toggle a chip, arrows move between chips, and each chip pops in on a quick spring. The time opens columns on desktop and a wheel sheet on phones. Every change rewrites the expression at once: the sentence under the fields says it back ("Every weekday at 9:00 AM") and screen readers hear it half a second after you stop, the expression chip copies with one click, and the next runs slide into place with the date, the time and how far away they are. Custom takes a raw expression, validated as you type with a message per field ("Hour must be between 0 and 23"), or five small boxes with By field; Enter never submits the form around it. Weekly or monthly with nothing picked says what is missing. Read-only keeps the sentence and the expression; reduced motion turns the slides into fades.

## Installation

```bash
npx wingo-ui@latest add cron-picker
```

Pro item: run `npx wingo-ui@latest login` once with a Pro account. The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add @wingo-ui/cron-picker` (needs the @wingo-ui registry with your API key in components.json)

Files:

- `components/ui/cron-picker.tsx`

npm dependencies: `npm i motion lucide-react`

Wingo UI dependencies (installed automatically):

- [Badge](https://wingo-ui.com/components/badge) ([Markdown](https://wingo-ui.com/components/badge.md))
- [Copy Button](https://wingo-ui.com/components/copy-button) ([Markdown](https://wingo-ui.com/components/copy-button.md))
- [Field](https://wingo-ui.com/components/field) ([Markdown](https://wingo-ui.com/components/field.md))
- [Input](https://wingo-ui.com/components/input) ([Markdown](https://wingo-ui.com/components/input.md))
- [Number Input](https://wingo-ui.com/components/number-input) ([Markdown](https://wingo-ui.com/components/number-input.md))
- [Segmented Control](https://wingo-ui.com/components/segmented-control) ([Markdown](https://wingo-ui.com/components/segmented-control.md))
- [Select](https://wingo-ui.com/components/select) ([Markdown](https://wingo-ui.com/components/select.md))
- [Time Picker](https://wingo-ui.com/components/time-picker) ([Markdown](https://wingo-ui.com/components/time-picker.md))
- [Toggle Group](https://wingo-ui.com/components/toggle-group) ([Markdown](https://wingo-ui.com/components/toggle-group.md))
- [useControllableState](https://wingo-ui.com/components/use-controllable-state) ([Markdown](https://wingo-ui.com/components/use-controllable-state.md))
- [useLocale](https://wingo-ui.com/components/use-locale) ([Markdown](https://wingo-ui.com/components/use-locale.md))
- [Date utils](https://wingo-ui.com/components/date-utils) ([Markdown](https://wingo-ui.com/components/date-utils.md))
- [Relative time](https://wingo-ui.com/components/relative-time) ([Markdown](https://wingo-ui.com/components/relative-time.md))
- [Motion presets](https://wingo-ui.com/components/motion) ([Markdown](https://wingo-ui.com/components/motion.md))
- [Tones](https://wingo-ui.com/components/tones) ([Markdown](https://wingo-ui.com/components/tones.md))
- [UIProvider](https://wingo-ui.com/components/ui-config) ([Markdown](https://wingo-ui.com/components/ui-config.md))

## Usage

```tsx
import { useState } from "react"
import { CronPicker, describeCron } from "@/components/ui/cron-picker"

export function ReportSchedule() {
  const [cron, setCron] = useState("0 9 * * 1-5")
  return (
    <div className="flex flex-col gap-3">
      <CronPicker
        label="Send the report"
        value={cron}
        onValueChange={setCron}
        locale="en-US"
        timeZone="America/New_York"
        name="schedule"
      />
      <p className="text-sm text-muted-foreground">{describeCron(cron, { locale: "en-US" })}</p>
    </div>
  )
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value?` | `string` |  | The controlled cron expression: 5 fields (minute hour day month weekday) with *, lists, ranges, steps, JAN / MON names and @daily-style macros. It is "" while a weekly or monthly tab has nothing picked. |
| `defaultValue?` | `string` | `"0 9 * * 1-5"` | The uncontrolled start. The tab it opens on comes from detectFrequency; anything the tabs cannot express (or an invalid expression) opens Custom. Try "*/15 9-17 * * 1-5" or "0 25 * * *". |
| `onValueChange?` | `(value: string) => void` |  | Every change from the tabs, chips, fields or the custom input, with the new expression (invalid custom text too, so a form can block saving). |
| `frequencies?` | `CronFrequency[] ("minutes" \| "hourly" \| "daily" \| "weekly" \| "monthly" \| "yearly" \| "custom")` | `"[\"minutes\", \"hourly\", \"daily\", \"weekly\", \"monthly\", \"custom\"]"` | The tabs, in order. Add "yearly" for dates like 1 January; custom only shows while allowCustom is on. |
| `showSummary?` | `boolean` | `true` | The sentence that says the schedule back, in Romanian or English, with correct plurals. |
| `showExpression?` | `boolean` | `true` | The expression as a mono chip with a copy button (and the time zone badge when timeZone is set). |
| `showNextRuns?` | `number` | `5` | How many next runs to list, with the date, the time and a relative label ("tomorrow"). 0 hides the list. |
| `allowCustom?` | `boolean` | `true` | The Custom tab: a raw expression input or five labelled boxes, validated as you type. |
| `minuteIntervals?` | `number[]` | `"[5, 10, 15, 30]"` | The choices for every N minutes. An incoming step outside the list (*/7) is added so it still shows. |
| `hourIntervals?` | `number[]` | `"[1, 2, 3, 4, 6, 12]"` | The choices for every N hours. |
| `weekStartsOn?` | `Weekday \| -1 (0 Sunday to 6 Saturday)` | `-1` | The weekday chip order. -1 follows the locale: Monday first in ro-RO, Sunday in en-US. |
| `timeZone?` | `string` | `""` | An IANA zone ("America/New_York") the expression is read in: the next runs are computed and shown in it, and a badge names it. Empty uses the device's zone. |
| `hourCycle?` | `"auto" \| "h12" \| "h23"` | `"auto"` | 12 or 24 hours for the time field, the sentence and the next runs. auto follows the locale (24h in ro-RO). |
| `layout?` | `"stacked" \| "split"` | `"stacked"` | split puts the fields on the left and the summary and next runs on the right once the picker is 672px wide (a container query); stacked always on phones. |
| `now?` | `Date \| number` |  | The moment the next runs count from. Default the current minute (useNow), with placeholder rows during server rendering. |
| `label?` | `ReactNode` | `""` | The field label above the picker. Clicking it focuses the frequency tabs. |
| `description?` | `ReactNode` | `""` | Helper text under the picker, replaced by the error while one shows. |
| `error?` | `ReactNode` | `""` | An error from your form under the picker; it also marks the field invalid. Custom expression errors show on the input itself. |
| `required?` | `boolean` | `false` | The required mark after the label and aria-required. |
| `invalid?` | `boolean` | `false` | The invalid state without a message (aria-invalid on the group). |
| `disabled?` | `boolean` | `false` | Dims and blocks every control inside. |
| `readOnly?` | `boolean` | `false` | Shows only the sentence and the expression (with copy), for a job list or a details page. |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | The tabs 32 / 40 / 48px, the chips 32 / 36 / 40px (44px on touch), the inline controls sm, sm and md, and the sentence text. |
| `variant?` | `"soft" \| "outline" \| "ghost"` | `"soft"` | The box of the inline select, number, time and custom inputs. |
| `radius?` | `"none" \| "sm" \| "md" \| "lg" \| "full"` | `"md"` | Corners of the tabs, the inputs and the chips (full makes round day chips). |
| `tone?` | `"neutral" \| "brand" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | The selected chips, the frequency thumb and the summary icon. |
| `color?` | `string` | `""` | Any CSS color for the selected chips and the thumb; replaces the tone. |
| `name?` | `string` | `""` | Adds a hidden input with the expression (empty while invalid), for plain form posts. The demo prints it under the picker. |
| `locale?` | `string` | `""` | Sentence language (ro and en built in, others through labels), weekday and month names, dates and times. Empty uses the UIProvider locale, then the browser's. The demo defaults to en-US. |
| `labels?` | `Partial<CronPickerLabels>` |  | Every string: frequencies and frequenciesShort, the sentence-row words (every, minutesUnit(n), atMinute, atTime), chip group names, custom tab strings, copy / copied, nextRuns, noRuns, invalid, pickDay, pickMonth, useFiveFields, outOfRange(field, min, max), badField(field), unknownTimeZone, increment / decrement (the minute steppers), timePicker (the time sheet: Done, Hours...), weekday and month names, and the sentence builders. A ro locale picks CRON_PICKER_LABELS_RO on its own. |
| `fieldProps?` | `Partial<FieldProps>` |  | More for the field wrapper: optional, optionalLabel, labelAction, hideLabel, className. |
| `id?` | `string` |  | The group's id; the label points at it. |
| `classNames?` | `Partial<Record<"field" \| "label" \| "description" \| "error" \| "frequency" \| "fields" \| "interval" \| "minute" \| "weekdays" \| "monthDays" \| "months" \| "time" \| "custom" \| "summary" \| "expression" \| "next" \| "run", string>>` |  | Extra classes for the inner parts. |
| `className?` | `string` |  | Classes for the root (the field wrapper when a label, description or error is set). |

## Parts

### parseCron (function)

The five fields ({ minute, hour, dayOfMonth, month, dayOfWeek }) with macros expanded, or null for anything that is not 5-field cron (6 or 7 fields, @reboot). Signature: (expr: string) => CronParts | null.

### isValidCron (function)

True for a valid 5-field expression. Signature: (expr: string) => boolean.

### validateCron (function)

Why an expression is invalid: the field count, a value out of range (with the field and bounds) or a syntax error in one field. Signature: (expr: string) => { valid: true; parts: CronParts } | { valid: false; error: CronError }.

### cronErrorMessage (function)

Turns a validateCron error into a sentence from the labels: useFiveFields, outOfRange(field, min, max), badField(field) or invalid. Pass DEFAULT_CRON_PICKER_LABELS for English. Signature: (error: CronError, labels: Pick<CronPickerLabels, "invalid" | "useFiveFields" | "outOfRange" | "badField">) => string.

### describeCron (function)

The sentence: "Every weekday at 9:00 AM", "Mondays, Wednesdays and Fridays at 8:30 AM", "On the 1st and 15th at 8:00 AM". Signature: (expr: string, { locale?, labels?, hourCycle? }) => string.

### getNextRuns (function)

The next runs after from, minute-accurate, up to 4 years ahead: skips 31 February, follows cron's day-of-month OR day-of-week rule when both are set, and reads the expression in timeZone. Signature: (expr: string, { from?, count = 5, timeZone? }) => Date[].

### detectFrequency (function)

The tab an expression opens on; "custom" for invalid ones and for what the tabs cannot express. Signature: (expr: string) => CronFrequency.

### DEFAULT_CRON_PICKER_LABELS (constant)

The English default labels, to spread and override. Type: CronPickerLabels.

### CRON_PICKER_LABELS_RO (constant)

The ready Romanian set (sentences with plurals and weekday articles: "lunea", "20 de minute"). Type: CronPickerLabels.

## Examples

- **Every 15 minutes**: A supplier invoice sync on */15, with the next three runs counted from 4:40 PM.
- **Monthly on the 1st and 15th**: Invoice reminders at 8:00 AM: tap day chips, the sentence and the expression follow.
- **Custom expression with validation**: An hour of 25 opens the custom tab with a field error; switch to By field to edit each part.
- **Split layout in a settings panel**: Fields on the left, summary and next runs on the right from 672px, with a yearly tab and a time zone.
- **Romanian**: Built-in Romanian sentences, Monday-first chips and a 24-hour clock from the ro-RO locale.
- **Read-only in a job list**: readOnly keeps only the sentence and the expression, compact enough for a row.

## See also

- [Time Picker](https://wingo-ui.com/components/time-picker) ([Markdown](https://wingo-ui.com/components/time-picker.md))
- [Toggle Group](https://wingo-ui.com/components/toggle-group) ([Markdown](https://wingo-ui.com/components/toggle-group.md))
- [Segmented Control](https://wingo-ui.com/components/segmented-control) ([Markdown](https://wingo-ui.com/components/segmented-control.md))
- [Date Picker](https://wingo-ui.com/components/date-picker) ([Markdown](https://wingo-ui.com/components/date-picker.md))
- [Scheduler](https://wingo-ui.com/components/scheduler) ([Markdown](https://wingo-ui.com/components/scheduler.md))

---

Canonical: https://wingo-ui.com/components/cron-picker
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt