# useInterrupt

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

## Overview [#overview]

`useInterrupt` handles agent interrupts and resumes execution with user input. It supports two interrupt flows:

- **AG-UI standard**: `RUN_FINISHED` with `outcome.type === "interrupt"`, carrying an `interrupts` array.
- **Custom event**: an `on_interrupt` custom event.

In your `render` callback, call `resolve(payload)` to resume or `cancel()` to cancel. See [`render`](#parameters) for every prop it receives. For a pause that is a tool call, use [`useHumanInTheLoop`](/reference/react-native/hooks/useHumanInTheLoop).

<Callout type="info">
  Re-exported from `@copilotkit/react-core/v2`. It is identical to the [React (V2) `useInterrupt`](/reference/v2/hooks/useInterrupt); only the import path differs.
</Callout>

The prebuilt [`CopilotChat`](/reference/react-native/components/CopilotChat#prebuilt-ui) and [`CopilotModal`](/reference/react-native/components/CopilotModal) from `@copilotkit/react-native/components` draw the in-chat interrupt element after the last message. The headless `CopilotChat`, `CopilotPopup`, and `CopilotSidebar` do not. With those, pass `renderInChat: false`, and the hook returns the element so you can render it in your own view. The element returned by `render` is a React Native element.

`event.value` is typed as `any` since the interrupt payload shape depends on your agent. Type-narrow it in your callbacks (e.g. `handler`, `enabled`, `render`) as needed.

## Signature [#signature]

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

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 once all open interrupts are addressed. For custom-event interrupts, resumes immediately via `command.resume = payload`.
    - `cancel(interruptId?)`: for standard interrupts, records `{ status: "cancelled" }` for the target interrupt and resumes once all are addressed. Not supported for custom-event interrupts (dismisses 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 agent of the surrounding headless
  `CopilotChat`, then `"default"`. `CopilotPopup`, `CopilotSidebar` and
  `CopilotModal` from `@copilotkit/react-native` wrap a headless `CopilotChat`,
  so a hook in their children gets their agent too.
</PropertyReference>

  <PropertyReference name="renderInChat" type="boolean" default="true">
    Controls where UI renders:
    - `true` (default): publishes the element to the CopilotKit core. The prebuilt `CopilotChat` and `CopilotModal` draw it. Headless views do not.
    - `false`: returns the interrupt element from the hook for manual placement. Use this with headless views.
  </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]

### Interrupt UI in your chat view [#interrupt-ui-in-your-chat-view]

```tsx
import { Text, TouchableOpacity, View } from "react-native";
import { useInterrupt } from "@copilotkit/react-native";

function ApprovalInterrupt() {
  const element = useInterrupt({
    renderInChat: false,
    render: ({ event, resolve }) => (
      <View style={{ padding: 12, borderWidth: 1, borderRadius: 8 }}>
        <Text>{event.value.question}</Text>
        <View style={{ marginTop: 8, flexDirection: "row", gap: 8 }}>
          <TouchableOpacity onPress={() => resolve({ approved: true })}>
            <Text>Approve</Text>
          </TouchableOpacity>
          <TouchableOpacity onPress={() => resolve({ approved: false })}>
            <Text>Reject</Text>
          </TouchableOpacity>
        </View>
      </View>
    ),
  });

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

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

```tsx
import { Text, TouchableOpacity, View } from "react-native";
import { useInterrupt } from "@copilotkit/react-native";

function ApprovalInterrupt() {
  const element = useInterrupt({
    renderInChat: false,
    render: ({ interrupt, resolve, cancel }) => (
      <View style={{ padding: 12, borderWidth: 1, borderRadius: 8 }}>
        <Text>{interrupt?.message ?? "Approve this action?"}</Text>
        <View style={{ marginTop: 8, flexDirection: "row", gap: 8 }}>
          <TouchableOpacity onPress={() => resolve({ approved: true })}>
            <Text>Approve</Text>
          </TouchableOpacity>
          <TouchableOpacity onPress={() => cancel()}>
            <Text>Cancel</Text>
          </TouchableOpacity>
        </View>
      </View>
    ),
  });

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

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

```tsx
import { Text, TouchableOpacity, View } from "react-native";
import { useInterrupt } from "@copilotkit/react-native";

function SidePanelInterrupt() {
  const element = useInterrupt({
    renderInChat: false,
    enabled: (event) => event.value.startsWith("approval:"),
    handler: async ({ event }) => ({ label: event.value.toUpperCase() }),
    render: ({ event, result, resolve }) => (
      <View style={{ borderWidth: 1, borderRadius: 8, padding: 12 }}>
        <Text style={{ fontWeight: "500" }}>{result?.label ?? ""}</Text>
        <Text style={{ marginTop: 8 }}>{event.value}</Text>
        <TouchableOpacity style={{ marginTop: 8 }} onPress={() => resolve({ accepted: true })}>
          <Text>Continue</Text>
        </TouchableOpacity>
      </View>
    ),
  });

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

## Behavior [#behavior]

- Standard interrupts are detected from `RUN_FINISHED` (`outcome.type === "interrupt"`); custom-event interrupts from `on_interrupt` events.
- `resolve`/`cancel` accumulate one response per open interrupt; the resume run starts once every open interrupt is addressed.
- Expired interrupts (past `expiresAt`) are not resumed.
- Interrupt UI is surfaced when the run finalizes.
- Starting a new run clears pending interrupt state.
- `event.value` is `any`; type-narrow in your callbacks as needed. For standard interrupts, `event.value` is the primary `Interrupt`.
- `render.result` is inferred from `handler` return type and is always `TResult | null`.
- If `handler` throws or rejects, `result` is set to `null`.
