Schedules | incld docs

Schedule composition

import {
 NextRun,
 RunHistory,
 ScheduleDetails,
 ScheduleList,
 ScheduleTrigger,
} from "@incld/react-schedules"

function Schedules() {
 const [selected, setSelected] = useState<string>()
 return (
  <>
   <ScheduleTrigger
    action="generate_report"
    defaultPayload={{ accountId: "acct_42" }}
   >
    Schedule report
   </ScheduleTrigger>
   <ScheduleList
    filters={{ action: "generate_report", status: "active" }}
    onSelect={schedule => setSelected(schedule.id)}
   />
   {selected && <ScheduleDetails scheduleId={selected} />}
   {selected && <NextRun scheduleId={selected} format="both" />}
   <RunHistory scheduleId={selected} />
  </>
 )
}

Component reference

Component	Required props	Optional props and behavior
ScheduleTrigger	action	defaultPayload?, defaultSchedule?, onCreated?, dialogTitle?, dialogClassName?, children, and native button props except onError. Opens a ScheduleComposer dialog.
ScheduleComposer	action	payload?, scheduleId?, initialSchedule?, defaultValue?, mode?, onSaved?, onCancel?, className?, classNames?, unstyled?. Creates or edits and previews five occurrences.
ScheduleList	—	filters, pageSize=25, renderItem, onSelect, className, and AsyncViewProps.
ScheduleDetails	scheduleId	onUpdated?, onDeleted?, className?, loading?, error?. Includes edit, pause/resume, and confirmed delete.
RunHistory	—	scheduleId, filters, locale, timeZone, and AsyncViewProps. Uses active-tenant runs when scheduleId is omitted.
NextRun	schedule or scheduleId	format=both (relative\|absolute\|both), locale?, timeZone?, className?. Passing schedule avoids a request.

ScheduleComposer details

Prop	Type	Notes
action	string	Stable declared action identifier.
payload	Record<string, unknown>?	Stored with the schedule and snapshotted into each run.
scheduleId	string?	Loads an existing schedule and makes edit the default mode.
initialSchedule	Schedule?	Seeds edit state without fetching. Usually pass it together with scheduleId and mode=edit.
defaultValue	Partial<ScheduleInput>?	Initial recurrence, timezone, and overlap policy for create mode.
mode	create \| edit	Defaults to edit when scheduleId exists, otherwise create.
onSaved	(Schedule) => void	Runs after the API mutation succeeds.
onCancel	() => void	When supplied, renders a Cancel control.
className	string?	Appended to the root form.
classNames	{root?, field?, actions?, preview?}	Stable style slots.
unstyled	boolean?	Removes component root/field default classes; structural and state markup remains.

Composer coverage is narrower than the recurrence API

The current UI creates once, daily, weekly, and monthly day-of-month schedules. The REST and SDK recurrence model also accepts first_monday, last_friday, last_day, startsAt, and end conditions; use the client or a custom form for those values.

Hooks

useSchedules(params?: ListSchedulesParams)

Lists schedules and refreshes on the provider interval and after provider mutations.

Returns AsyncState<Page<Schedule>>

useSchedule(id?: string)

Loads one schedule; stays defined but returns undefined when no ID is supplied.

Returns AsyncState<Schedule | undefined>

useRuns(params?: ListRunsParams, scheduleId?: string)

Lists schedule-specific or active-tenant runs.

Returns AsyncState<Page<Run>>

useSchedulePreview(input?: {recurrence: Recurrence})

Requests five canonical future occurrences.

Returns AsyncState<SchedulePreview | undefined>

useScheduleMutation()

Creates a fresh idempotency key per user mutation and refreshes provider consumers after success.

Returns {pending, error, create, update, pause, resume, remove}

Styling contracts

ScheduleComposer exposes explicit slots. Other components accept the documented className or custom render function where available. Prefer CSS variables for product-wide styling and renderItem for a fully custom list row.

Generated TypeScript signatures

Interface	Prop	Type	Required
NextRunProps	schedule	Schedule	No
NextRunProps	scheduleId	string	No
NextRunProps	format	'relative' \| 'absolute' \| 'both'	No
NextRunProps	locale	string	No
NextRunProps	timeZone	string	No
NextRunProps	className	string	No
RunHistoryProps extends AsyncViewProps	scheduleId	string	No
RunHistoryProps extends AsyncViewProps	filters	ListRunsParams	No
RunHistoryProps extends AsyncViewProps	locale	string	No
RunHistoryProps extends AsyncViewProps	timeZone	string	No
RunHistoryProps extends AsyncViewProps	className	string	No
ScheduleComposerProps	action	string	Yes
ScheduleComposerProps	payload	Record<string, unknown>	No
ScheduleComposerProps	scheduleId	string	No
ScheduleComposerProps	initialSchedule	Schedule	No
ScheduleComposerProps	defaultValue	Partial<ScheduleInput>	No
ScheduleComposerProps	mode	'create' \| 'edit'	No
ScheduleComposerProps	onSaved	(schedule: Schedule) => void	No
ScheduleComposerProps	onCancel	() => void	No
ScheduleComposerProps	className	string	No
ScheduleComposerProps	classNames	ScheduleComposerSlots	No
ScheduleComposerProps	unstyled	boolean	No
ScheduleComposerSlots	root	string	No
ScheduleComposerSlots	field	string	No
ScheduleComposerSlots	actions	string	No
ScheduleComposerSlots	preview	string	No
ScheduleDetailsProps extends AsyncViewProps	scheduleId	string	Yes
ScheduleDetailsProps extends AsyncViewProps	onUpdated	(schedule: Schedule) => void	No
ScheduleDetailsProps extends AsyncViewProps	onDeleted	(schedule: Schedule) => void	No
ScheduleDetailsProps extends AsyncViewProps	className	string	No
ScheduleListProps extends AsyncViewProps	filters	ListSchedulesParams	No
ScheduleListProps extends AsyncViewProps	pageSize	number	No
ScheduleListProps extends AsyncViewProps	renderItem	(schedule: Schedule) => ReactNode	No
ScheduleListProps extends AsyncViewProps	onSelect	(schedule: Schedule) => void	No
ScheduleListProps extends AsyncViewProps	className	string	No
ScheduleTriggerProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onError'>	action	string	Yes
ScheduleTriggerProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onError'>	defaultPayload	Record<string, unknown>	No
ScheduleTriggerProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onError'>	defaultSchedule	ScheduleComposerProps['defaultValue']	No
ScheduleTriggerProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onError'>	onCreated	(schedule: Schedule) => void	No
ScheduleTriggerProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onError'>	dialogTitle	string	No
ScheduleTriggerProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onError'>	dialogClassName	string	No