Hooks

The SDK ships four opinionated hooks for React components. Pick the one that matches the level of control you need:

Hook	Use when
useSwiftpatchUpdate()	You want the full state machine — phase, pending release, progress, error, plus applyNow/dismiss.
useSwiftpatchProgress()	You only need a progress bar during download.
useSwiftpatchReady(callback)	You want to fire a callback the moment an update is ready, without subscribing to other events.
useOnResumeApply()	You want updates to silently apply when the user foregrounds the app. One-line drop-in.

All hooks are SSR-safe. They must be used inside a <SwiftPatchProvider>.

useSwiftpatchUpdate()

The canonical hook. Returns everything you need to render update UI.

import { useSwiftpatchUpdate } from '@swiftpatch/react-native';

function UpdateBar() {
  const { phase, pendingUpdate, progress, error, applyNow, dismiss, clearError } =
    useSwiftpatchUpdate();

  if (phase === 'idle') return null;

  if (phase === 'downloading' && progress) {
    return <Text>Downloading… {progress.percent}%</Text>;
  }

  if (phase === 'ready' && pendingUpdate) {
    return (
      <View>
        <Text>Update ready: v{pendingUpdate.version}</Text>
        <Button title="Apply now" onPress={applyNow} />
        <Button title="Later" onPress={dismiss} />
      </View>
    );
  }

  if (phase === 'error' && error) {
    return (
      <View>
        <Text>Update failed: {error.message}</Text>
        <Button title="Dismiss" onPress={clearError} />
      </View>
    );
  }

  return null;
}

Return shape:

interface UseSwiftpatchUpdateReturn {
  state: UpdateState;
  phase: 'idle' | 'checking' | 'downloading' | 'ready' | 'applying' | 'error';
  pendingUpdate: UpdateInfo | null;
  progress: { loaded: number; total: number; percent: number } | null;
  error: SwiftPatchError | null;
  applyNow: () => Promise<void>;
  dismiss: () => Promise<void>;
  clearError: () => void;
}

• phase mirrors the orchestrator's lifecycle.
• applyNow() installs the ready update and restarts the app.
• dismiss() writes a dismissal flag keyed on the release hash, so the same release will not prompt again. A newer release surfaces normally.

useSwiftpatchProgress()

A lean hook for progress bars only.

import { useSwiftpatchProgress } from '@swiftpatch/react-native';

function DownloadBar() {
  const { percent, loaded, total, active } = useSwiftpatchProgress();

  if (!active) return null;

  return (
    <View style={{ height: 4, backgroundColor: '#222' }}>
      <View
        style={{
          height: 4,
          width: `${percent}%`,
          backgroundColor: '#2563eb',
        }}
      />
      <Text>{Math.round(loaded / 1024)} / {Math.round(total / 1024)} KB</Text>
    </View>
  );
}

Return shape:

interface UseSwiftpatchProgressReturn {
  loaded: number;
  total: number;
  percent: number;    // 0–100
  hash: string;
  active: boolean;    // true while a download is in flight
}

useSwiftpatchReady(callback)

Fire a callback exactly once when each new update becomes ready. Useful for custom notifications.

import { useSwiftpatchReady } from '@swiftpatch/react-native';

function NotifyWhenReady() {
  useSwiftpatchReady((update) => {
    Toast.show(`Update ready: v${update.version}`);
  });
  return null;
}

The callback is stable across re-renders (the hook pins it in a ref), so you can pass inline functions without subscription churn.

useOnResumeApply()

Drop this into a component once and updates silently apply when the user foregrounds the app.

import { useOnResumeApply } from '@swiftpatch/react-native';

function SilentAutoApply() {
  useOnResumeApply({ enabled: true });
  return null;
}

Props:

interface Options {
  enabled?: boolean; // default: true
}

The hook:

1. Listens for update-ready and tracks the latest ready release.
2. On AppState transition to active, calls Swiftpatch.applyNow() if a ready release exists.
3. Respects your active UpdatePolicy — if policy is silent and nothing is ready, it no-ops.

Can I use the legacy useSwiftPatch() hook?

Yes. It's still exported and returns the full state + actions object used by older integrations:

import { useSwiftPatch } from '@swiftpatch/react-native';

const {
  status,
  availableUpdate,
  downloadProgress,
  checkForUpdate,
  downloadUpdate,
  installUpdate,
  restart,
  rollback,
  /* ... */
} = useSwiftPatch();

The opinionated hooks above are the recommended path for new code.

Next steps

• UI components — <UpdateBanner>, <UpdateBlocker>, <UpdateOnboarding>.
• Methods — the imperative Swiftpatch.* API.
• Events — every event the SDK emits.