# useInterrupt

> React hook for handling agent interrupt events and resuming execution with user input

## Overview [#overview]

`useInterrupt` shows your UI when the agent pauses for input. Call `resolve(payload)` to resume the run. Call `cancel()` to cancel it. The hook supports the AG-UI standard interrupt flow and the `on_interrupt` custom-event flow. See [Behavior](#behavior).

For a full walkthrough, see [Pausing the Agent for Input](/human-in-the-loop/useInterrupt). If your agent has no interrupt, use [`useHumanInTheLoop`](/reference/hooks/useHumanInTheLoop).

By default, interrupt UI is rendered inside `<CopilotChat>` automatically. If you set `renderInChat: false`, the hook returns the element so you can place it manually.

## Signature [#signature]

```tsx
import { useInterrupt } from "@copilotkit/react-core/v2";

function useInterrupt<
  TResult = never,
  TRenderInChat extends boolean | undefined = undefined,
>(
  config: UseInterruptConfig<any, TResult, TRenderInChat>,
): TRenderInChat extends false
  ? React.ReactElement | null
  : TRenderInChat extends true | undefined
    ? void
    : React.ReactElement | null | void;
```

## Parameters [#parameters]

<PropertyReference name="config" type="UseInterruptConfig<any, TResult, TRenderInChat>" required>
  Interrupt configuration.

  <PropertyReference name="render" type="(props: InterruptRenderProps<any, TResult | null>) => React.ReactElement" required>
    Render callback for interrupt UI. Called when an interrupt is available. The callback receives:
    - `event` -- interrupt event (`{ name, value }`). `value` is `any`; type-narrow in your callback as needed.
    - `interrupt` -- the primary standard `Interrupt` (`{ id, reason, message?, toolCallId?, responseSchema?, expiresAt?, metadata? }`), or `null` for custom-event interrupts.
    - `interrupts` -- all open standard interrupts (empty array for custom-event interrupts).
    - `result` -- inferred from `handler` return type, or `null`
    - `resolve(payload?, interruptId?)` -- for standard interrupts, records `{ status: "resolved", payload }` for the target interrupt (defaults to the primary) and submits the resume once all open interrupts are addressed. For custom-event interrupts, maps to `command.resume = payload`.
    - `cancel(interruptId?)` -- for standard interrupts, records `{ status: "cancelled" }` for the target interrupt and submits once all open interrupts are addressed. For custom-event interrupts, dismisses the pending interrupt without resuming.
  </PropertyReference>

<PropertyReference
  name="handler"
  type="(props: InterruptHandlerProps) => TResult | PromiseLike<TResult>"
>
  Optional preprocessing callback. Runs before rendering and can return sync or
  async data that is exposed as `result` in `render`. `TResult` is automatically
  inferred from the handler's return type. If the handler throws/rejects,
  `result` is `null`.
</PropertyReference>

<PropertyReference name="enabled" type="(event: InterruptEvent) => boolean">
  Optional filter. Return `false` to ignore matching interrupts for this hook
  instance.
</PropertyReference>

<PropertyReference name="agentId" type="string">
  Optional agent id. Defaults to the currently configured chat agent.
</PropertyReference>

  <PropertyReference name="renderInChat" type="boolean" default="true">
    Controls where UI renders:
    - `true` (default): publishes interrupt UI into `<CopilotChat>`
    - `false`: returns interrupt element from the hook for manual placement
  </PropertyReference>
</PropertyReference>

## Return Value [#return-value]

<PropertyReference name="element" type="Conditional by renderInChat">
  Return type is inferred from `renderInChat`:
  - `renderInChat: false` -> `React.ReactElement | null`
  - `renderInChat: true` or omitted -> `void`
  - dynamic boolean -> `React.ReactElement | null | void`
</PropertyReference>

## Usage [#usage]

### In-chat interrupt UI (default) [#in-chat-interrupt-ui-default]

This sample reads a custom-event interrupt whose value holds a `question` field. For a standard interrupt, read `interrupt.message` instead, as in the AG-UI standard sample below.

```tsx
function ApprovalInterrupt() {
  useInterrupt({
    render: ({ event, resolve }) => {
      const value =
        typeof event.value === "string" ? JSON.parse(event.value) : event.value;
      return (
        <div className="p-3 border rounded">
          <p>{value.question}</p>
          <div className="mt-2 flex gap-2">
            <button onClick={() => resolve({ approved: true })}>Approve</button>
            <button onClick={() => resolve({ approved: false })}>Reject</button>
          </div>
        </div>
      );
    },
  });

  return null;
}
```

### Manual placement with async preprocessing [#manual-placement-with-async-preprocessing]

```tsx
function SidePanelInterrupt() {
  const element = useInterrupt({
    renderInChat: false,
    enabled: (event) => event.value.startsWith("approval:"),
    handler: async ({ event }) => ({ label: event.value.toUpperCase() }),
    render: ({ event, result, resolve }) => (
      <aside className="rounded border p-3">
        <div className="font-medium">{result?.label ?? ""}</div>
        <div className="mt-2">{event.value}</div>
        <button className="mt-2" onClick={() => resolve({ accepted: true })}>
          Continue
        </button>
      </aside>
    ),
  });

  return <>{element}</>;
}
```

### AG-UI standard interrupt (approve / cancel) [#ag-ui-standard-interrupt-approve--cancel]

```tsx
function ApprovalInterrupt() {
  useInterrupt({
    render: ({ interrupt, resolve, cancel }) => (
      <div className="p-3 border rounded">
        <p>{interrupt?.message ?? "Approve this action?"}</p>
        <div className="mt-2 flex gap-2">
          <button onClick={() => resolve({ approved: true })}>Approve</button>
          <button onClick={() => cancel()}>Cancel</button>
        </div>
      </div>
    ),
  });
  return null;
}
```

## Behavior [#behavior]

- Standard interrupts are detected from `RUN_FINISHED` (`outcome.type === "interrupt"`, carrying an `interrupts` array); custom-event interrupts from `on_interrupt` custom events. For standard interrupts, `render` and `handler` receive `interrupt` (the primary one) and `interrupts` (the full open set). Standard takes precedence if both appear in the same run.
- `resolve`/`cancel` accumulate one response per open interrupt; the resume run starts once every open interrupt is addressed. Standard resumes use a fresh `runId` on the same thread and identify the pending interrupts through `resume[].interruptId`.
- Expired interrupts (past `expiresAt`) are not resumed. The hook logs an error and clears pending state.
- Interrupt UI is surfaced when the run finalizes.
- Starting a new run clears pending interrupt state.
- `render.result` is inferred from `handler` return type and is always `TResult | null`.
- If `handler` throws or rejects, `result` is set to `null`.
