Approval Workflow
A reusable approval workflow engine with form-driven definition builder, runtime timeline, and framework-agnostic callbacks for internal LGU systems.
Interactive Demo
Build a workflow definition, execute runtime decisions, and observe step transitions and overdue signaling.
Department Head Review
Configure approvers, rule, and SLA.
Approvers
Budget Validation
Configure approvers, rule, and SLA.
Approvers
Final Approval
Configure approvers, rule, and SLA.
Approvers
Purchase Request Approval
Route PR records across office, budget, and final signatory approvals.
Department Head Review
Validate completeness of request details.
Budget Validation
Check allotment availability and compliance.
Final Approval
Final executive sign-off.
Runtime Controls
Action Logs
No actions yet.
Installation
Install directly from the MICTO registry endpoint.
pnpm dlx shadcn@latest add https://micto-ui-kit.misangono.net/r/micto/approval-workflow.jsonUsage
Controlled workflow definition plus controlled runtime state using the `useApprovalWorkflow` hook.
import * as React from "react"
import {
ApprovalWorkflowBuilder,
ApprovalWorkflowTimeline,
ApprovalWorkflowActions,
createWorkflowInstance,
useApprovalWorkflow,
type WorkflowDefinition,
} from "@/components/micto/approval-workflow"
const definition: WorkflowDefinition = {
title: "Leave Request Approval",
steps: [
{
id: "department-head",
title: "Department Head",
rule: "all",
slaHours: 24,
approvers: [{ id: "u-head-1", name: "Dept Head" }],
},
{
id: "hr-review",
title: "HR Review",
rule: "any",
slaHours: 24,
approvers: [
{ id: "u-hr-1", name: "HR Officer A" },
{ id: "u-hr-2", name: "HR Officer B" },
],
},
],
}
export default function Example() {
const approverOptions = [
{ value: "u-head-1", label: "Dept Head", role: "MICTO" },
{ value: "u-hr-1", label: "HR Officer A", role: "HR" },
{ value: "u-hr-2", label: "HR Officer B", role: "HR" },
]
const [value, setValue] = React.useState(definition)
const [instance, setInstance] = React.useState(() => createWorkflowInstance(definition))
const workflow = useApprovalWorkflow({
value,
onChange: setValue,
instance,
onInstanceChange: setInstance,
onOverdue: (step) => console.log("Overdue step:", step.id),
})
return (
<div className="space-y-4">
<ApprovalWorkflowBuilder
value={workflow.definition}
onChange={workflow.setDefinition}
approverOptions={approverOptions}
showAdvancedFields={false}
/>
<ApprovalWorkflowTimeline
definition={workflow.definition}
instance={workflow.instance}
/>
<ApprovalWorkflowActions
definition={workflow.definition}
instance={workflow.instance}
approverId="u-head-1"
onAction={workflow.submitAction}
/>
</div>
)
}Builder Props
Authoring-focused props for definition editing and validation events.
| Prop | Type | Default | Description |
|---|---|---|---|
| value | WorkflowDefinition | undefined | Controlled workflow definition object. |
| defaultValue | WorkflowDefinition | seeded default | Initial definition for uncontrolled usage. |
| readonly | boolean | false | Disables authoring inputs and mutation controls. |
| onChange | (value) => void | undefined | Fires whenever the workflow definition changes. |
| onDefinitionChange | (value) => void | undefined | Alias callback for definition updates. |
| onValidationError | (errors) => void | undefined | Returns validation issues (missing steps, approvers, ids, etc.). |
| approverOptions | WorkflowApproverOption[] | [] | Static approver source rendered by SearchSelect (backend ids as values). |
| onResolveApprovers | (query) => Promise<WorkflowApproverOption[]> | undefined | Async approver search callback for large user directories. |
| showAdvancedFields | boolean | false | Reveals manual `stepId` and manual approver controls for power users. |
Runtime Props
Callbacks and state channels for runtime step execution.
| Prop | Type | Default | Description |
|---|---|---|---|
| instance | WorkflowInstanceState | undefined | Controlled runtime instance state. |
| defaultInstance | WorkflowInstanceState | auto-created | Initial runtime instance in uncontrolled mode. |
| onInstanceChange | (next) => void | undefined | Called whenever runtime state mutates. |
| onAction | (action, next) => void | undefined | Emits on approve/reject/return/delegate decisions. |
| onStepChange | (step, index) => void | undefined | Emits when the active step changes. |
| onOverdue | (step, index, instance) => void | undefined | Called when current step exceeds SLA and is flagged overdue. |
Actions Props
Props for action decision controls tied to an active approver.
| Prop | Type | Default | Description |
|---|---|---|---|
| definition | WorkflowDefinition | Workflow definition for action context. | |
| instance | WorkflowInstanceState | Current runtime state used for action gating. | |
| approverId | string | Actor id performing the decision action. | |
| onAction | (action) => void | Callback to submit approve/reject/return decisions. |