Command Palette

Search for a command to run...

GitHub
ComponentsApproval Workflow

Approval Workflow

A reusable approval workflow engine with form-driven definition builder, runtime timeline, and framework-agnostic callbacks for internal LGU systems.

React
Workflow
LGU Internal

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

Department Head(MICTO)

Budget Validation

Configure approvers, rule, and SLA.

Approvers

Budget Officer A(Budget)
Budget Officer B(Budget)

Final Approval

Configure approvers, rule, and SLA.

Approvers

Municipal Mayor(LCE)

Purchase Request Approval

Route PR records across office, budget, and final signatory approvals.

in progress

Department Head Review

Validate completeness of request details.

in progress
Rule: allApprovers: 1SLA: 24h

Budget Validation

Check allotment availability and compliance.

pending
Rule: anyApprovers: 2SLA: 12h

Final Approval

Final executive sign-off.

pending
Rule: allApprovers: 1SLA: 48h

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.json

Usage

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.

PropTypeDefaultDescription
valueWorkflowDefinitionundefinedControlled workflow definition object.
defaultValueWorkflowDefinitionseeded defaultInitial definition for uncontrolled usage.
readonlybooleanfalseDisables authoring inputs and mutation controls.
onChange(value) => voidundefinedFires whenever the workflow definition changes.
onDefinitionChange(value) => voidundefinedAlias callback for definition updates.
onValidationError(errors) => voidundefinedReturns validation issues (missing steps, approvers, ids, etc.).
approverOptionsWorkflowApproverOption[][]Static approver source rendered by SearchSelect (backend ids as values).
onResolveApprovers(query) => Promise<WorkflowApproverOption[]>undefinedAsync approver search callback for large user directories.
showAdvancedFieldsbooleanfalseReveals manual `stepId` and manual approver controls for power users.

Runtime Props

Callbacks and state channels for runtime step execution.

PropTypeDefaultDescription
instanceWorkflowInstanceStateundefinedControlled runtime instance state.
defaultInstanceWorkflowInstanceStateauto-createdInitial runtime instance in uncontrolled mode.
onInstanceChange(next) => voidundefinedCalled whenever runtime state mutates.
onAction(action, next) => voidundefinedEmits on approve/reject/return/delegate decisions.
onStepChange(step, index) => voidundefinedEmits when the active step changes.
onOverdue(step, index, instance) => voidundefinedCalled when current step exceeds SLA and is flagged overdue.

Actions Props

Props for action decision controls tied to an active approver.

PropTypeDefaultDescription
definitionWorkflowDefinitionWorkflow definition for action context.
instanceWorkflowInstanceStateCurrent runtime state used for action gating.
approverIdstringActor id performing the decision action.
onAction(action) => voidCallback to submit approve/reject/return decisions.