Pro

Cron Picker React component for Tailwind CSS v4

Q: How do I install Cron Picker?

Run npx wingo-ui@latest add cron-picker. It also adds the Wingo UI items it builds on (Badge, Copy Button, Field, Input, Number Input and 11 more) and the npm packages motion and lucide-react. With shadcn, add the @wingo-ui registry with your API key, then run npx shadcn@latest add @wingo-ui/cron-picker.

v1.0.0Added in 1.0.0

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

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.

Cron Picker is a Pro React component in the React input components category, written in TypeScript for React 19 and Tailwind CSS v4. It installs as source with npx wingo-ui@latest add cron-picker, together with Badge, Copy Button, Field, Input, Number Input and 11 more and the npm packages motion and lucide-react.

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

npx wingo-ui@latest add cron-picker

Cron Picker is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import CronPicker from @/components/ui/cron-picker.

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

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.
defaultValuedefault "0 9 * * 1-5"
string
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).
frequenciesdefault "["minutes", "hourly", "daily", "weekly", "monthly", "custom"]"
CronFrequency[] ("minutes" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "custom")
The tabs, in order. Add "yearly" for dates like 1 January; custom only shows while allowCustom is on.
showSummarydefault true
boolean
The sentence that says the schedule back, in Romanian or English, with correct plurals.
showExpressiondefault true
boolean
The expression as a mono chip with a copy button (and the time zone badge when timeZone is set).
showNextRunsdefault 5
number
How many next runs to list, with the date, the time and a relative label ("tomorrow"). 0 hides the list.
allowCustomdefault true
boolean
The Custom tab: a raw expression input or five labelled boxes, validated as you type.
minuteIntervalsdefault "[5, 10, 15, 30]"
number[]
The choices for every N minutes. An incoming step outside the list (*/7) is added so it still shows.
hourIntervalsdefault "[1, 2, 3, 4, 6, 12]"
number[]
The choices for every N hours.
weekStartsOndefault -1
Weekday | -1 (0 Sunday to 6 Saturday)
The weekday chip order. -1 follows the locale: Monday first in ro-RO, Sunday in en-US.
timeZonedefault ""
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.
hourCycledefault "auto"
"auto" | "h12" | "h23"
12 or 24 hours for the time field, the sentence and the next runs. auto follows the locale (24h in ro-RO).
layoutdefault "stacked"
"stacked" | "split"
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.
labeldefault ""
ReactNode
The field label above the picker. Clicking it focuses the frequency tabs.
descriptiondefault ""
ReactNode
Helper text under the picker, replaced by the error while one shows.
errordefault ""
ReactNode
An error from your form under the picker; it also marks the field invalid. Custom expression errors show on the input itself.
requireddefault false
boolean
The required mark after the label and aria-required.
invaliddefault false
boolean
The invalid state without a message (aria-invalid on the group).
disableddefault false
boolean
Dims and blocks every control inside.
readOnlydefault false
boolean
Shows only the sentence and the expression (with copy), for a job list or a details page.
sizedefault "md"
"sm" | "md" | "lg"
The tabs 32 / 40 / 48px, the chips 32 / 36 / 40px (44px on touch), the inline controls sm, sm and md, and the sentence text.
variantdefault "soft"
"soft" | "outline" | "ghost"
The box of the inline select, number, time and custom inputs.
radiusdefault "md"
"none" | "sm" | "md" | "lg" | "full"
Corners of the tabs, the inputs and the chips (full makes round day chips).
tonedefault "neutral"
"neutral" | "brand" | "success" | "warning" | "danger" | "info"
The selected chips, the frequency thumb and the summary icon.
colordefault ""
string
Any CSS color for the selected chips and the thumb; replaces the tone.
namedefault ""
string
Adds a hidden input with the expression (empty while invalid), for plain form posts. The demo prints it under the picker.
localedefault ""
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.

Dependencies

motion lucide-react badge copy-button field input number-input segmented-control select time-picker toggle-group use-controllable-state use-locale date-utils relative-time motion tones ui-config

Files

components/ui/cron-picker.tsx

FAQ

Is the React Cron Picker component free?

The preview, props and docs are free; copying the source needs a Pro plan. See plans.

How do I install Cron Picker?

Run npx wingo-ui@latest add cron-picker. It also adds the Wingo UI items it builds on (Badge, Copy Button, Field, Input, Number Input and 11 more) and the npm packages motion and lucide-react. With shadcn, add the @wingo-ui registry with your API key, then run npx shadcn@latest add @wingo-ui/cron-picker.

How does Cron Picker behave on phones?

Used in

Automation Builder Page

More React input components

Currency Input Date Time Picker Email Input Emoji Picker File Upload Filter Builder

All 40 React input components

Articles using this component

React Cron Generator: Schedules Without Writing Cron
Component guidesOct 19, 20269 min read

Pro

Cron Picker React component for Tailwind CSS v4

v1.0.0Added in 1.0.0

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

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

npx wingo-ui@latest add cron-picker

Cron Picker is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import CronPicker from @/components/ui/cron-picker.

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

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.
defaultValuedefault "0 9 * * 1-5"
string
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).
frequenciesdefault "["minutes", "hourly", "daily", "weekly", "monthly", "custom"]"
CronFrequency[] ("minutes" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "custom")
The tabs, in order. Add "yearly" for dates like 1 January; custom only shows while allowCustom is on.
showSummarydefault true
boolean
The sentence that says the schedule back, in Romanian or English, with correct plurals.
showExpressiondefault true
boolean
The expression as a mono chip with a copy button (and the time zone badge when timeZone is set).
showNextRunsdefault 5
number
How many next runs to list, with the date, the time and a relative label ("tomorrow"). 0 hides the list.
allowCustomdefault true
boolean
The Custom tab: a raw expression input or five labelled boxes, validated as you type.
minuteIntervalsdefault "[5, 10, 15, 30]"
number[]
The choices for every N minutes. An incoming step outside the list (*/7) is added so it still shows.
hourIntervalsdefault "[1, 2, 3, 4, 6, 12]"
number[]
The choices for every N hours.
weekStartsOndefault -1
Weekday | -1 (0 Sunday to 6 Saturday)
The weekday chip order. -1 follows the locale: Monday first in ro-RO, Sunday in en-US.
timeZonedefault ""
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.
hourCycledefault "auto"
"auto" | "h12" | "h23"
12 or 24 hours for the time field, the sentence and the next runs. auto follows the locale (24h in ro-RO).
layoutdefault "stacked"
"stacked" | "split"
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.
labeldefault ""
ReactNode
The field label above the picker. Clicking it focuses the frequency tabs.
descriptiondefault ""
ReactNode
Helper text under the picker, replaced by the error while one shows.
errordefault ""
ReactNode
An error from your form under the picker; it also marks the field invalid. Custom expression errors show on the input itself.
requireddefault false
boolean
The required mark after the label and aria-required.
invaliddefault false
boolean
The invalid state without a message (aria-invalid on the group).
disableddefault false
boolean
Dims and blocks every control inside.
readOnlydefault false
boolean
Shows only the sentence and the expression (with copy), for a job list or a details page.
sizedefault "md"
"sm" | "md" | "lg"
The tabs 32 / 40 / 48px, the chips 32 / 36 / 40px (44px on touch), the inline controls sm, sm and md, and the sentence text.
variantdefault "soft"
"soft" | "outline" | "ghost"
The box of the inline select, number, time and custom inputs.
radiusdefault "md"
"none" | "sm" | "md" | "lg" | "full"
Corners of the tabs, the inputs and the chips (full makes round day chips).
tonedefault "neutral"
"neutral" | "brand" | "success" | "warning" | "danger" | "info"
The selected chips, the frequency thumb and the summary icon.
colordefault ""
string
Any CSS color for the selected chips and the thumb; replaces the tone.
namedefault ""
string
Adds a hidden input with the expression (empty while invalid), for plain form posts. The demo prints it under the picker.
localedefault ""
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.

Dependencies

motion lucide-react badge copy-button field input number-input segmented-control select time-picker toggle-group use-controllable-state use-locale date-utils relative-time motion tones ui-config

Files

components/ui/cron-picker.tsx

FAQ

Is the React Cron Picker component free?

The preview, props and docs are free; copying the source needs a Pro plan. See plans.

How do I install Cron Picker?

How does Cron Picker behave on phones?

Used in

Automation Builder Page

More React input components

Currency Input Date Time Picker Email Input Emoji Picker File Upload Filter Builder

All 40 React input components

Articles using this component

React Cron Generator: Schedules Without Writing Cron
Component guidesOct 19, 20269 min read

Cron Picker React component for Tailwind CSS v4

Add to a project

Usage

Props

Parts

parseCron

isValidCron

validateCron

cronErrorMessage

describeCron

getNextRuns

detectFrequency

DEFAULT_CRON_PICKER_LABELS

CRON_PICKER_LABELS_RO

Examples

Every 15 minutes

Monthly on the 1st and 15th

Custom expression with validation

Split layout in a settings panel

Romanian

Read-only in a job list

Dependencies

Files

FAQ

Is the React Cron Picker component free?

How do I install Cron Picker?

How does Cron Picker behave on phones?

See also

Used in

More React input components

Articles using this component

Automated report: weekly sales

Next runs

Cron Picker React component for Tailwind CSS v4

Add to a project

Usage

Props

Parts

parseCron

isValidCron

validateCron

cronErrorMessage

describeCron

getNextRuns

detectFrequency

DEFAULT_CRON_PICKER_LABELS

CRON_PICKER_LABELS_RO

Examples

Every 15 minutes

Monthly on the 1st and 15th

Custom expression with validation

Split layout in a settings panel

Romanian

Read-only in a job list

Dependencies

Files

FAQ

Is the React Cron Picker component free?

How do I install Cron Picker?

How does Cron Picker behave on phones?

See also

Used in

More React input components

Articles using this component

Automated report: weekly sales

Next runs